Laravel Mygls Laravel Package

Getting Started

1. composer require webapix/laravel-mygls
2. Publish the config: php artisan vendor:publish --tag=mygls-config (check src/ for the exact tag — the package is small enough that the service provider is short).
3. Add credentials to .env. MyGLS auth is username/password plus a clientNumber that identifies your GLS contract:

   MYGLS_USERNAME=
   MYGLS_PASSWORD=
   MYGLS_CLIENT_NUMBER=
   MYGLS_ENV=test    # or prod
   

4. Resolve the client from the container (or a facade, if the provider aliases one). Check config/mygls.php for the binding name — the package is a thin wrapper around webapix/mygls-php, so most of the real API surface lives behind that client.

Where to look first: this package is deliberately small. Read the service provider, the config file, and then jump to the underlying webapix/mygls-php SDK's README — the parcel DTOs, status enums, and endpoint methods are defined there, not here. The Laravel layer mostly gives you config-driven client construction and container bindings.

First use case: create a single parcel and print its label. Do this against the test environment first:

• Build a parcel payload (recipient address, weight, parcel count, optional COD/insurance).
• POST to parcel creation; get back a parcel number.
• Request the label; you'll receive a PDF (usually base64 in a JSON field).
• Store the parcel number on your Order model and save the PDF to a private disk.

Implementation Patterns

Inject, don't resolve ad hoc. Bind the client once via the service provider and resolve it through the container. Facades are fine in controllers, but jobs and services should receive the client (or a small wrapper of your own) via constructor injection so you can swap it in tests.

Wrap the SDK, don't call it everywhere. Create a small GlsService/ParcelBuilder in your app that takes your Order model and returns a ready-to-send parcel DTO. The MyGLS DTOs are verbose and country-sensitive; keeping that mapping in one place pays off as soon as address formats, COD, or weight rules change.

Queue label generation and parcel creation. MyGLS responses can be slow (multiple seconds), and label endpoints do real work (PDF rendering). Do creation and label printing inside ShouldQueue jobs, and store the returned parcel number as the idempotency anchor on the order. Retry with a small backoff; do not retry blindly without an order-level lock, because a duplicate parcel in GLS is painful to clean up.

Batch labels at end-of-day. The common workflow is: orders get parcel numbers as they're placed, then a scheduled command asks MyGLS for PDFs for all the day's parcels and drops them in a single archive for the picker. Loop the label endpoint per parcel number; don't try to invent a "batch" call that doesn't exist.

Poll status on a schedule. Tracking isn't webhook-pushed by MyGLS. Run an everyFifteenMinutes command that takes recent parcel numbers and pulls status, then map the returned status codes onto your own order states. Cache the last known status so a flaky response doesn't roll an order backwards.

Schedule pickup once per day. The pickup endpoint is per-client and generally per-day. Make it idempotent by keying on date + client — calling it twice for the same day will either be rejected or create a duplicate.

Test with a fake. In tests, bind a stub implementation of the parcel client that returns canned responses. The package's config-driven construction makes this easy: override the binding in TestCase::setUp.

Gotchas and Tips

• clientNumber is required on nearly every call. It's not derived from your username; you'll get cryptic auth errors if it's blank or mismatched with the environment.
• Sandbox vs production is a separate host and separate credentials. Pickups often don't fully work in the sandbox. Don't treat a passing sandbox pickup as proof the production flow is wired correctly.
• Labels arrive as base64 in JSON, not raw PDF. Decode before writing to disk and set Content-Type: application/pdf when streaming to the browser. Streaming the raw string produces a corrupt download that looks like a corrupted PDF rather than an encoding bug.
• Units are fixed. Weight is kg, dimensions are cm, and some fields round or reject decimals. Validate in your wrapper before the HTTP call.
• Address validation is country-specific. Hungarian, Czech, Slovak, and Romanian parcel schemas differ (street/number split, house-number quirks, city vs. district). Build the DTO per destination country rather than one generic mapper.
• COD and insurance are country- and currency-sensitive. A COD amount with the wrong currency or above the contract limit fails at the API, not in your UI. Enforce the rules on your side.
• Status codes are integers, not strings. Map them to an enum in one place; the SDK may expose constants but the raw values still come back in responses. Log unknown codes rather than swallowing them.
• Date-times are local to the GLS tenant. Don't send UTC blindly — the pickup date at least is interpreted in the client's local timezone.
• Log the raw request/response during bring-up. The SDK is typed enough to be helpful, but error payloads from MyGLS can be terse. Wrap the HTTP client with Laravel's logger (or the SDK's debug flag) and capture bodies while you're stabilising the integration. Turn this off in production — labels and addresses are sensitive.
• Extension point worth knowing: the service provider binds the underlying client, so you can override it with a decorator to add retries, logging, or metrics without forking the package. That's the cleanest place to add resilience, since the package itself is thin.
• Small package, small surface. With 17 stars and a recent release cadence, don't expect extensive docs or a wide user base to Google. Budget time to read vendor/webapix/mygls-php/src directly — it's the authoritative reference for DTO fields and endpoint behaviour.