{"id":21976794,"url":"https://github.com/stuartapp/stuart-client-php","last_synced_at":"2025-08-21T20:31:51.434Z","repository":{"id":22162611,"uuid":"81437497","full_name":"StuartApp/stuart-client-php","owner":"StuartApp","description":"Stuart PHP client","archived":false,"fork":false,"pushed_at":"2024-01-15T12:53:43.000Z","size":4745,"stargazers_count":17,"open_issues_count":2,"forks_count":19,"subscribers_count":57,"default_branch":"master","last_synced_at":"2024-12-13T03:14:41.730Z","etag":null,"topics":["delivery","php-library","stuart"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/StuartApp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-02-09T10:15:09.000Z","updated_at":"2024-01-15T13:55:26.000Z","dependencies_parsed_at":"2022-08-24T07:30:46.958Z","dependency_job_id":"6c5f5bcb-cd84-4fb9-9288-00615d5eddf9","html_url":"https://github.com/StuartApp/stuart-client-php","commit_stats":{"total_commits":190,"total_committers":19,"mean_commits":10.0,"dds":"0.23684210526315785","last_synced_commit":"e3dac78fd0d5cc7aac798c9b82a497a42b043019"},"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StuartApp%2Fstuart-client-php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StuartApp%2Fstuart-client-php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StuartApp%2Fstuart-client-php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StuartApp%2Fstuart-client-php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/StuartApp","download_url":"https://codeload.github.com/StuartApp/stuart-client-php/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230532442,"owners_count":18240792,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["delivery","php-library","stuart"],"created_at":"2024-11-29T16:12:19.013Z","updated_at":"2024-12-20T04:06:52.415Z","avatar_url":"https://github.com/StuartApp.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Codeship Status for StuartApp/stuart-client-php](https://app.codeship.com/projects/aa042f30-b15a-0137-cdf6-4ac72e591a58/status?branch=master)](https://app.codeship.com/projects/363052)\n\n# Stuart PHP Client\n\nFor a complete documentation of all endpoints offered by the Stuart API, you can visit [Stuart API documentation](https://api-docs.stuart.com).\n\n### Changelog\n\nVisit [Changelog](CHANGELOG.md)\n\n### Running the demo\n\n```shell script\ncd demo\ndocker build -t stuartphpdemo .\nexport PATH_TO_PROJECT=\"/PUT/HERE/YOUR/PATH/TO/PROJECT/stuart-client-php\"\ndocker run -v $PATH_TO_PROJECT/src:/app/vendor/stuartapp/stuart-client-php/src stuartphpdemo\n```\n\n## Install\n\nVia Composer:\n\n```bash\n$ composer require stuartapp/stuart-client-php\n```\n\n## Usage\n\n1. [Initialize Client](#initialize-client)\n2. [Create a Job](#create-a-job)\n   1. [Minimalist](#minimalist)\n   2. [Complete](#complete)\n      1. [With scheduling at pickup](#with-scheduling-at-pickup)\n      1. [With scheduling at drop off](#with-scheduling-at-dropoff)\n      1. [With stacking (multi-drop)](#with-stacking-multi-drop)\n3. [Get a Job](#get-a-job)\n4. [Cancel a Job](#cancel-a-job)\n5. [Validate a Job](#validate-a-job)\n6. [Cancel a delivery](#cancel-a-delivery)\n7. [Get a pricing](#get-a-pricing)\n8. [Get a job eta to pickup](#get-a-job-eta-to-pickup)\n9. [Custom requests](#custom-requests)\n\n### Import the library\n\nIf composer is not installed, install it:\n\n```shell script\n$ curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer\n```\n\nAdd the library to your project:\n\n```shell script\n$ composer require stuartapp/stuart-client-php\n```\n\n### Autoloading\n\nIn order to load all the classes from this library, just execute the autoload at the beginning of the Stuart code\n\n```php\n\u003c?php\nrequire __DIR__ . '/vendor/autoload.php';\n\n$environment = \\Stuart\\Infrastructure\\Environment::SANDBOX;\n```\n\n### Get credentials\n\nFor Sandbox (testing environment, couriers are bots)\nhttps://dashboard.sandbox.stuart.com/settings/api\n\nFor Production (real world, real couriers)\nhttps://dashboard.stuart.com/settings/api\n\n### Initialize client\n\n```php\n$environment = \\Stuart\\Infrastructure\\Environment::SANDBOX;\n$api_client_id = 'REPLACE_BY_YOU_CLIENT_ID_HERE'; // can be found here: https://admin.sandbox.stuart.com/client/api\n$api_client_secret = 'REPLACE_BY_YOUR_CLIENT_SECRET_HERE'; // can be found here: https://admin.sandbox.stuart.com/client/api\n$authenticator = new \\Stuart\\Infrastructure\\Authenticator($environment, $api_client_id, $api_client_secret);\n\n$httpClient = new \\Stuart\\Infrastructure\\HttpClient($authenticator)\n\n$client = new \\Stuart\\Client($httpClient);\n```\n\nYou can also pass your own Guzzle client instance to the `\\Stuart\\HttpClient` constructor:\n\n```php\n$guzzleClient = new \\Guzzle\\Client();\n$httpClient = new \\Stuart\\Infrastructure\\HttpClient($authenticator, $guzzleClient);\n```\n\nThis can be useful if you need to attach middlewares to the Guzzle client.\n\n### Caching\n\nIt's highly recommended adding a caching mechanism for the authentication process.\nTo do so, simply extend the `Psr\\SimpleCache\\CacheInterface` class and implement your own version.\n\nThere's a cache based on disk available out of the box for you to use.\nTo use it, simply modify the Authentication class initialization and pass the cache implementation in the constructor:\n\n```php\n$diskCache = new \\Stuart\\Cache\\DiskCache(\"stuart_cache.txt\");\n$authenticator = new \\Stuart\\Infrastructure\\Authenticator($environment, $api_client_id, $api_client_secret, $diskCache);\n```\n\n##### Debugging token cache issues\n\nYou can initialize the DiskCache, Authenticator and HttpClient classes by passing a `true` value to the last constructor parameter of these classes.\n\n### Create a Job\n\n**Important**: Even if you can create a Job with a minimal set of parameters, we **highly recommend** that you fill as many information as\nyou can in order to ensure the delivery process goes well.\n\n#### Minimalist\n\n##### Package size based\n\n```php\n$job = new \\Stuart\\Job();\n\n$job-\u003eaddPickup('46 Boulevard Barbès, 75018 Paris');\n\n$job-\u003eaddDropOff('156 rue de Charonne, 75011 Paris')\n    -\u003esetPackageType('small');\n\n$client-\u003ecreateJob($job);\n```\n\n#### Complete\n\n##### Package size based\n\n```php\n$job = new \\Stuart\\Job();\n\n$job-\u003eaddPickup('46 Boulevard Barbès, 75018 Paris')\n    -\u003esetComment('Wait outside for an employee to come.')\n    -\u003esetContactCompany('KFC Paris Barbès')\n    -\u003esetContactFirstName('Martin')\n    -\u003esetContactLastName('Pont')\n    -\u003esetContactPhone('+33698348756');\n\n$job-\u003eaddDropOff('156 rue de Charonne, 75011 Paris')\n    -\u003esetPackageType('small')\n    -\u003esetComment('code: 3492B. 3e étage droite. Sonner à Durand.')\n    -\u003esetContactCompany('Durand associates.')\n    -\u003esetContactFirstName('Alex')\n    -\u003esetContactLastName('Durand')\n    -\u003esetContactPhone('+33634981209')\n    -\u003esetPackageDescription('Pizza box.')\n    -\u003esetClientReference('12345678ABCDE'); // Must be unique\n\n$client-\u003ecreateJob($job);\n```\n\n#### With scheduling at pickup\n\nFor more information about job scheduling you should [check our API documentation](https://stuart.api-docs.io/v2/jobs/scheduling-a-job).\n\n```php\n$job = new \\Stuart\\Job();\n\n$pickupAt = new \\DateTime('now', new DateTimeZone('Europe/Paris'));\n$pickupAt-\u003eadd(new \\DateInterval('PT2H'));\n\n$job-\u003eaddPickup('46 Boulevard Barbès, 75018 Paris')\n    -\u003esetPickupAt($pickupAt);\n\n$job-\u003eaddDropOff('156 rue de Charonne, 75011 Paris')\n    -\u003esetPackageType('small');\n\n$client-\u003ecreateJob($job);\n```\n\n#### With scheduling at dropoff\n\nFor more information about job scheduling you should [check our API documentation](https://stuart.api-docs.io/v2/jobs/scheduling-a-job).\n\nPlease note that this feature can only be used with only one dropoff.\n\n```php\n$job = new \\Stuart\\Job();\n\n$dropoffAt = new \\DateTime('now', new DateTimeZone('Europe/Paris'));\n$dropoffAt-\u003eadd(new \\DateInterval('PT2H'));\n\n$job-\u003eaddPickup('46 Boulevard Barbès, 75018 Paris');\n\n$job-\u003eaddDropOff('156 rue de Charonne, 75011 Paris')\n    -\u003esetPackageType('small')\n    -\u003esetDropoffAt($dropoffAt);\n\n$client-\u003ecreateJob($job);\n```\n\n#### With fleet targeting\n\n```php\n$job = new \\Stuart\\Job();\n\n$job-\u003eaddPickup('46 Boulevard Barbès, 75018 Paris');\n\n$job-\u003eaddDropOff('156 rue de Charonne, 75011 Paris')\n    -\u003esetPackageType('small');\n\n$job-\u003esetFleets(array(1));\n\n$client-\u003ecreateJob($job);\n```\n\n#### With end customer time window information (used for metrics purposes only)\n\n```php\n$job = new \\Stuart\\Job();\n\n$job-\u003eaddPickup('46 Boulevard Barbès, 75018 Paris');\n\n$now = new DateTime();\n$later = new DateTime();\n$later = $later-\u003emodify('+15 minutes');\n\n$job-\u003eaddDropOff('156 rue de Charonne, 75011 Paris')\n    -\u003esetPackageType('small')\n    -\u003esetEndCustomerTimeWindowStart(new DateTime())\n    -\u003esetEndCustomerTimeWindowEnd($later);\n\n$client-\u003ecreateJob($job);\n```\n\n#### With stacking (multi-drop)\n\n##### Package size based\n\n```php\n$job = new \\Stuart\\Job();\n\n$job-\u003eaddPickup('46 Boulevard Barbès, 75018 Paris')\n    -\u003esetComment('Wait outside for an employee to come.')\n    -\u003esetContactCompany('KFC Paris Barbès')\n    -\u003esetContactFirstName('Martin')\n    -\u003esetContactLastName('Pont')\n    -\u003esetContactPhone('+33698348756');\n\n$job-\u003eaddDropOff('156 rue de Charonne, 75011 Paris')\n    -\u003esetPackageType('small')\n    -\u003esetComment('code: 3492B. 3e étage droite. Sonner à Durand.')\n    -\u003esetContactCompany('Durand associates.')\n    -\u003esetContactFirstName('Alex')\n    -\u003esetContactLastName('Durand')\n    -\u003esetContactPhone('+33634981209')\n    -\u003esetPackageDescription('Red packet.')\n    -\u003esetClientReference('12345678ABCDE'); // Must be unique;\n\n$job-\u003eaddDropOff('12 avenue claude vellefaux, 75010 Paris')\n    -\u003esetPackageType('small')\n    -\u003esetComment('code: 92A42. 2e étage gauche')\n    -\u003esetContactFirstName('Maximilien')\n    -\u003esetContactLastName('Lebluc')\n    -\u003esetContactPhone('+33632341209')\n    -\u003esetPackageDescription('Blue packet.')\n    -\u003esetClientReference('ABCDE213124'); // Must be unique\n\n$client-\u003ecreateJob($job);\n```\n\n### Get a Job\n\nOnce you successfully created a Job you can retrieve it this way:\n\n```php\n$jobId = 126532;\n$job = $client-\u003egetJob($jobId);\n```\n\nOr when you create a new Job:\n\n```php\n$job = new \\Stuart\\Job();\n\n$job-\u003eaddPickup('46 Boulevard Barbès, 75018 Paris');\n\n$job-\u003eaddDropOff('156 rue de Charonne, 75011 Paris')\n    -\u003esetPackageType('small');\n\n$jobWithRoute = $client-\u003ecreateJob($job);\n\n$jobWithRoute-\u003egetDeliveries();\n```\n\nThe Stuart API determine the optimal route on your behalf,\nthat's why the `getDeliveries()` method will return an empty\narray when the Job has not been created yet. The `getDeliveries()`\nmethod will return an array of `Delivery` as soon as the Job is created.\n\n### Cancel a job\n\nOnce you successfully created a Job you can cancel it in this way:\n\n```php\n$jobId = 126532;\n$result = $client-\u003ecancelJob($jobId);\n```\n\nThe result will hold the boolean value `true` if the job was cancelled. If\nthere was an error, it will contain an error object.\n\nFor more details about how cancellation works, please refer to our [dedicated documentation section](https://stuart.api-docs.io/v2/jobs/job-cancellation).\n\n### Validate a Job\n\nBefore creating a Job you can validate it (control delivery area \u0026 address format). Validating a Job is **optional** and does not prevent you from creating a Job.\n\n```php\n$job = new \\Stuart\\Job();\n\n$job-\u003eaddPickup('46 Boulevard Barbès, 75018 Paris');\n\n$job-\u003eaddDropOff('156 rue de Charonne, 75011 Paris')\n    -\u003esetPackageType('small');\n\n$result = $client-\u003evalidateJob($job);\n```\n\nThe result will hold the boolean value `true` if the job is valid. If\nthere was an error, it will contain an error object.\n\n### Validate an address\n\nWe encourage to validate an address to find out if we can pickup / deliver there. Phone number is optional only for those places that the address is specific enough.\n\n```php\n$client-\u003evalidatePickupAddress('Pau Claris, 08037 Barcelona', '+34677777777');\n$client-\u003evalidatePickupAddress('Pau Claris 186, 08037 Barcelona');\n$client-\u003evalidateDropoffAddress('Pau Claris, 08037 Barcelona', '+34677777777');\n```\n\n### Cancel a delivery\n\nOnce you successfully created a Delivery you can cancel it in this way:\n\n```php\n$deliveryId = 126532;\n$result = $client-\u003ecancelDelivery($deliveryId);\n```\n\n### Get a pricing\n\nBefore creating a Job you can ask for a pricing. Asking for a pricing is **optional** and does not prevent you from creating a Job.\n\n```php\n$job = new \\Stuart\\Job();\n\n$job-\u003eaddPickup('46 Boulevard Barbès, 75018 Paris');\n\n$job-\u003eaddDropOff('156 rue de Charonne, 75011 Paris')\n    -\u003esetPackageType('small');\n\n$pricing = $client-\u003egetPricing($job);\n\n$pricing-\u003eamount; // example: 11.5\n$pricing-\u003ecurrency; // example: \"EUR\"\n```\n\n### Get a job ETA to pickup\n\nBefore creating a Job you can ask for an estimated time of arrival at the pickup location (expressed in seconds).\nAsking for ETA is **optional** and does not prevent you from creating a job.\n\n```php\n$job = new \\Stuart\\Job();\n\n$job-\u003eaddPickup('46 Boulevard Barbès, 75018 Paris');\n\n$job-\u003eaddDropOff('156 rue de Charonne, 75011 Paris')\n    -\u003esetPackageType('small');\n\n$eta = $client-\u003egetEta($job);\n\n$eta-\u003eeta; // example: 672\n```\n\n### Custom requests\n\nYou can also send requests on your own without relying on the `\\Stuart\\Client`.\nIt allows you to use endpoints that are not yet available on the `\\Stuart\\Client` and enjoy the `\\Stuart\\Authenticator`.\n\n```php\n$apiResponse = $httpClient-\u003eperformGet('/v2/jobs?page=1');\n$apiResponse-\u003esuccess();\n$apiResponse-\u003egetBody();\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstuartapp%2Fstuart-client-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstuartapp%2Fstuart-client-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstuartapp%2Fstuart-client-php/lists"}