Awesome
PHP SDK
<p align="center"> </p> <!-- BADGES_START --> <!-- BADGES_END -->A framework for building simple to use SDKs in PHP 8.0 and above.
Installation
composer require juststeveking/php-sdk
Purpose
The purpose of this package is to provide a consistent and interoperable way to build PHP SDKs to work with 3rd party APis.
Usage
Working with this library is relatively simple, and an example can be found in the demo and examples directories.
The basic concept is that you will need to provide:
- PSR-17 Request and Response Factory.
- PSR-7 Messages
Inside this library we are using a PSR-18 implementation allowing you to connect the pieces together under the hood and provide SDK functionality using a replaceable set of components.
I highly recommend either:
To handle the Http PSRs as they are lightweight and designed to be simple and PSR compliant.
Building the SDK
To begin with we need to be able to build our SDK, to do this we can either use the constructor
or use the static build
method.:
SDK constructor
To create an SDK instance; simply pass through a uri, a Http Client that uses auto-discovery to find the available PSR-18 client, an authentication strategy, and an instance of the Container
.
use JustSteveKing\HttpAuth\Strategies\BasicStrategy;
use JustSteveKing\HttpSlim\HttpClient;
use JustSteveKing\UriBuilder\Uri;
use JustSteveKing\PhpSdk\SDK;
use PHPFox\Container\Container;
$sdk = new SDK(
uri: Uri::fromString('https://www.domain.com'),
client: HttpClient::build(),
strategy: new BasicStrategy(
authString: base64_encode("username:password")
),
container: Container::getInstance(),
);
SDK build
To use the static build method, the only requirement is to pass through a uri. If you want to set a custom Authentication Strategy you can also pass this through otherwise it will default to a Null Strategy.
use JustSteveKing\UriBuilder\Uri;
use JustSteveKing\PhpSdk\SDK;
$sdk = SDK::build(
uri: 'https://www.domain.com',
);
Adding Resources to our SDK
Each Resource you add to your SDK requires 2 things:
- Implements
ResourceContract
- Extends
AbstractResource
Your resource should look like this:
use JustSteveKing\PhpSdk\Contracts\ResourceContract;
use JustSteveKing\PhpSdk\Resources\AbstractResource;
class TestResource extends AbstractResource implements ResourceContract
{
protected string $path = '/test';
public static function name(): string
{
return 'tests';
}
}
The Path property allows you to set the uri path for this resource, and the static name method is how this resource is stored on the container.
To add this resource to the SDK, you can use the add method:
$sdk->add(
name: TestResource::name(),
resource: TestResource::class,
);
Internally this will add the resource onto container and inject the SDK into the constructor, allowing you to access the Http Client and other aspects of the SDK.
Calling a Resource
Now that you have added a resource to the SDK, you are able to call it using the PHP magic __get method:
$response = $sdk->tests->get();
This will return a nice PSR-7 response for you to work with inside your SDK code.
API
The below documents the API of the PHP-SDK:
SDK class
Your own SDK class should extend the base SDK class for easier integration.
__construct(URI $uri, HttpClient $client, Container $container, null|StrategyInterface $strategy)
The SDK constructor.static build(string $uri, null|StrategyInterface $strategy = null, null|Container = null): SDK
This static build method allows the defaults to be set for you to get an SDK quickly.add(string $name, string $resource): self
The add method allows you to add resources onto the SDK container, and checks that the resource being passed extends the AbstractResource and implements the ResourceContract.uri(): Uri
Return the setup instance of UriBuilder that is being used, to allow you to manipulate the URI string.client(): HttpClient
Return the setup instance of the HttpClient that is being used, to allow you to enforce any changes that are required.strategy(): StrategyInterface
Returns the setup instance of the Authentication Strategy that is being used, to allow you to export the auth header array.container(): Container
Returns the setup instance of the Container, to allow you to bind make and work with the container directly should it be required.__get(string $name): ResourceContract
Returns a build instance of the called Resource if it has been added to the container.
AbstractResource class
Your resources must all extend the Abstract Resource class.
__construct(SDK $sdk, null|string $path = null, string $authHeader = 'Bearer', array $with = [], array $relations = [], bool $strictRelations = false, null|string $load = null)
The Resource constructor.sdk(): SDK
Return the setup instance of the SDK that has been passed through to the resource.getWith(): array
Return an array of relations to sideload onto the request.getLoad(): string|null
Return a string or null if a specific resource identifier has been passed in.load(string|int $identifier): self
The load method allows you to set a specific resource identifier to look for on an API.uri(Uri $uri): self
The uri method allows you to completely override the URI Builder on the SDK.client(HttpClient $http): self
The client method allows you to completely override the Http Client on the SDK.strategy(StrategyInterface $strategy): self
The strategy method allows you to completely override the Authentication Strategy on the SDK.loadPath(): self
Loads the path from the resource into to URI builder on the SDK.get(): ResponseInterface
Performs a GET request to the resource path, to return a list of resources.find(string|int $identifier): ResponseInterface
Performs a GET request to the resource path with an identifier appended to it, to return a single resource.create(array $data): ResponseInterface
Performs a POST request to the resource path, to create a new single resource.update($identifier, array $data, string $method = 'patch'): ResponseInterface
Performs either a PATCH or PUT request to the resource path with an identifier appended to it, to update a single resource.delete(string|int $identifier): ResponseInterface
Performs a DELETE request to the resource path with an identifier appended to it, to remove a resource.where(string $key, $value): self
Builds the query parameters in a famility query builder style syntax.
ResourceContract Interface
Your resources must implement the ResourceContract interface.
static name(): string
Returns a string representation of the resource name, to allow it to be bound the the SDK container.
It is highly recommended that you use all of these internally in your API to give you the ability to control the process.
Building an SDK
To build an SDK, you can simply extend the SDK like so:
use Demo\Resources\Server;
use JustSteveKing\HttpAuth\Strategies\NullStrategy;
use JustSteveKing\HttpSlim\HttpClient;
use JustSteveKing\PhpSdk\SDK;
use JustSteveKing\UriBuilder\Uri;
use PHPFox\Container\Container;
class MySDK extends SDK
{
public function __construct()
{
parent::__construct(
uri: Uri::fromString(
uri: 'https://www.domain.tld',
),
client: HttpClient::build(),
container: Container::getInstance(),
strategy: new NullStrategy()),
);
}
public static function boot(): MySDK
{
$client = new MySDK();
$client->add(
name: TestResource::name(),
resource: TestResource::class,
);
return $client;
}
}
Testing
TO run the test:
composer run test
Credits
LICENSE
The MIT LIcense (MIT). Please see License File for more information.