Sg Parser Bundle Laravel Package

Getting Started

A fresh 1.0.0 means there's no upgrade path to worry about — you're adopting from zero, so the goal of the first hour is to confirm the package does what its README claims before you wire it into anything real.

1. Install and let discovery do its job. composer require <vendor>/<package> and check composer.json in the package for extra.laravel.providers / aliases. If it's a modern package, you shouldn't need to touch config/app.php at all.
2. Read in this order: README.md → the service provider in src/ → config/*.php → CHANGELOG.md. The service provider is the single best map of what the package registers (bindings, singletons, commands, routes, migrations, event listeners).
3. Publish what's publishable. php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" and inspect the tags it exposes. Publish config first, assets/migrations second — you often don't want the migrations if the package loads them itself.
4. Smoke-test in isolation. A throwaway php artisan tinker session or a single feature test is faster than integrating and debugging at the same time. Resolve the package's main class from the container and hit its simplest public method.

First use case: whatever the package's headline feature is, exercise it once end-to-end (config → service → observable output) in a scratch test before you build anything on top of it.

Implementation Patterns

Wrap it, don't scatter it. Resolve the package through constructor injection in one or two of your own service classes rather than calling it from controllers, jobs, and models. When 1.x shifts an API (and it will), you edit one adapter instead of a dozen call sites.

final class ShippingCalculator
{
    public function __construct(private \Vendor\Package\Client $client) {}

    public function quote(Order $order): Money
    {
        return $this->client->quote($order->toPackagePayload());
    }
}

Config over code. Anything the package exposes in its published config should live in config/<package>.php with values coming from env(). Never edit files under vendor/ — they vanish on the next composer update.

Test double at the boundary. If the package ships a fake, contract, or swap()/fake() helper, use it in your feature tests so you're not hitting a real API in CI. If it doesn't, bind your own interface in a test service provider and fake that.

Async and side effects. If the package dispatches events, queues jobs, or fires webhooks, register listeners in your own EventServiceProvider rather than modifying package internals. That's the supported extension point and it survives upgrades.

Pin and lock. "<vendor>/<package>": "^1.0" in composer.json, and commit composer.lock. On a 1.0.0, minors may still carry behaviour changes; treat every composer update of this package as something to review, not something to batch.

Gotchas and Tips

• Config caching bites on first install. After publishing config, run php artisan config:clear (and route:clear, view:clear if relevant). "My env var isn't picked up" is almost always a stale cached config in bootstrap/cache/.
• Auto-discovery is silent when it fails. If the package appears unregistered, check composer.json → extra.laravel.dont-discover in your app, and run php artisan about to see what Laravel actually booted. composer dump-autoload after adding a package you installed manually.
• Migrations: loaded vs. published. Some packages run their migrations from the package path; others require you to publish them. Check the provider's loadMigrationsFrom() vs. publishes(). Running vendor:publish on a package that already loads migrations gives you duplicate tables.
• Publish tags are package-specific. If vendor:publish with no arguments floods you with options, use --tag= — but the tag names are the package's choice; read the provider to find them rather than guessing.
• Facades hide the container binding. When debugging "class not found" or "target not instantiable", app()->bound(Foo::class) and app()->make(Foo::class) in tinker tell you instantly whether it's a registration problem or a usage problem.
• 1.0.0 is a promise about stability, not maturity. Expect the first few patch releases to fix edge cases. Watch the CHANGELOG for 1.0.x entries before upgrading in production, and don't build deep assumptions on undocumented methods — prefer the public contract if one exists.
• Where to extend: macros (if the package registers Macroable), custom drivers/managers, published config, and events are the stable seams. Subclassing package internals is the seam that breaks.
• Logs first, debugger second. Bind a listener to the package's events and Log::debug() the payload — it's usually faster than stepping through vendor code to find out what shape the data is actually in.