A Laravel package for querying the Builder API
You can install the package via composer:
composer require rs/builder-api
By default, the API client will attempt to find settings from the following environment variables
# .env
BUILDER_SITE_NAME=sitename # the name of the site in Builder
BUILDER_PUBLISHED=true # whether to query the published or unpublished data of the Builder site (defaults to true if not defined)
BUILDER_API_USER=builderuser
BUILDER_API_KEY=key-123
Alternatively, you can publish the config file and define your settings there:
php artisan vendor:publish --provider="RedSnapper\Builder\BuilderApiServiceProvider" --tag="config"
# config/builder-api.php
return [
'site' => 'sitename',
'published' => true,
'user' => 'builderuser',
'password' => 'key-123',
];
If you provide both a user and password then basic authentication will be attempted.
Alternatively you can provide just a user - this will add an X-USER
header to the request. This will only work if your
application lives on the same network as the Builder instance
You can use the BuilderApi
facade to create a PendingRequest
. You can overwrite any configuration using the fluent
methods available on this object.
$pendingRequest = BuilderApi::new();
$pendingRequest->forSite('sitename')
->withAuth('builderuser', 'key-123')
->unpublished()
->get('apiPages');
To make a GET request provide the Builder macro name and optionally provide parameters as a second argument.
$response = $pendingRequest->forSite('sitename')->get('apiPages', ['foo', 'bar']);
You can also make a request directly with the facade. This will make use of the configuration defined in your config file or environment variables
$response = BuilderApi::get('apiPages'); // returns BuilderResponse object
If you don't want to use the facade, you can type-hint the BuilderRequestFactory
class in your constructor methods or use app()->make()
use RedSnapper\Builder\BuilderRequestFactory;
public function __construct(BuilderRequestFactory $factory)
{
$this->factory = $factory;
# or...
$factory = app()->make(BuilderRequestFactory::class);
$pendingRequest = $factory->new();
$response = $pendingRequest->get('apiPages');
}
When a request is made a BuilderResponse
object is returned, this provides
methods for retrieving the Builder data or Builder error messages on a failed request.
$data = $response->data(); # get json decoded data
if($response->failed()) {
$errorMsg = $response->errorMsg();
}
Below is the full list of methods provided to help you analyse the response
$response->data();
$response->successful();
$response->failed();
$response->errorMsg(); # error msg provided by Builder
$response->status(); # status code of the response
$response->throw(); # throw an exception if a server or client error occurred
$response->getResponse(); # get the underlying 'Illuminate\Http\Client\Response' object
vendor/bin/phpunit
Please see CHANGELOG for more information on what has changed recently.
Please see CONTRIBUTING for details.
The MIT License (MIT). Please see Licence File for more information.