Eloquent Laravel Package

Getting Started

The 1.0.0 release note is one line — "compatibility with erdiko/core 1.0" — which tells you two things before you write any code: this is an Erdiko ecosystem package, not a Laravel package, and its version is now coupled to a specific erdiko/core major line. Treat package:^1.0 and erdiko/core:^1.0 as a pair you upgrade together.

First steps, in order:

1. composer.json — read the require block for the exact erdiko/core constraint, and the autoload block for the PSR-4 prefix. In a Laravel app you already have Illuminate\* and often other micro-framework globals; knowing the namespace root up front prevents collision surprises.
2. README.md / docs/ — look for a bootstrap or registration snippet. If the only example is an Erdiko app/ bootstrap call, there is no Laravel path and you are writing a bridge.
3. src/ — find the entry class. Grep for ServiceProvider, Facade, or providers in composer.json's extra key. If neither exists, there is no Laravel integration and php artisan vendor:publish will not do anything.
4. tests/ — the fastest honest spec of intended usage. Existing tests show the minimum wiring required to instantiate the package.

First use case: in a scratch Erdiko 1.0 app (or a throwaway Laravel app plus a manual new of the entry class), install, instantiate the main class, and run the simplest documented operation. That single smoke test tells you whether the package needs an Erdiko container, request object, or config singleton to function — which determines how much adapter work a Laravel integration costs.

Implementation Patterns

Pin the pair. Require both packages explicitly rather than relying on transitive resolution:

composer require erdiko/core:^1.0 vendor/package:^1.0
composer show erdiko/core          # confirm the resolved version
composer why erdiko/core           # confirm nothing else is pulling a conflicting line

Commit composer.lock in applications. The 1.0.0 note is a compatibility statement, not a feature statement — the risk surface is the core dependency, not new API.

Wrap, don't sprinkle. If the package's classes leak into controllers, jobs, and Blade views, the Erdiko coupling becomes unremovable. Define a narrow interface in your app and implement it with the package inside:

interface ReportGenerator { public function build(array $input): string; }

final class ErdikoReportGenerator implements ReportGenerator
{
    public function __construct(private \Vendor\Package\Generator $inner) {}

    public function build(array $input): string
    {
        return $this->inner->render($input);
    }
}

Bind it in a ServiceProvider and the rest of the app stays framework-agnostic and testable.

Bootstrap explicitly. If the package expects Erdiko's bootstrap to have run (constants, app() helper, config singleton), do that setup in a dedicated service provider's register() or boot() — never in a controller. Make it idempotent so queue workers and Octane don't re-run it into a broken state.

Test at two levels. Unit-test your adapter with the package mocked. Add one integration test that exercises the real package so a erdiko/core bump breaks a named test rather than production.

CI matrix. Run the PHP versions supported by erdiko/core 1.0 — check that package's composer.json, don't assume. Include a lowest-dependencies job (composer update --prefer-lowest) so the 1.0.0 floor is actually exercised.

Gotchas and Tips

• This is not a Laravel package. No facades, no publishable config, no artisan commands, no auto-discovery unless extra.laravel.providers is present. Budget for a bridge, or don't adopt it.
• Autoload and global collisions. Two frameworks in one process is the classic failure: duplicate helper functions, conflicting constants, or two Container singletons. Run composer dump-autoload -o and check class_exists() on the entry class before diagnosing deeper.
• Version coupling is the real hazard. A patch bump of erdiko/core inside the 1.0 line can still break this package if it reaches into internals. Pin, lock, and upgrade both deliberately in one PR.
• No upgrade path documented. Because 1.0.0's notes mention only core compatibility, do the archaeology yourself: git diff <0.x-tag>..1.0.0 -- composer.json and diff the public API surface. A jump to 1.0.0 is a SemVer stability promise — confirm the API you depend on actually still exists.
• Debugging checklist. composer diagnose → dump-autoload -o → verify PSR-4 path case matches the namespace (works on macOS, fails on Linux CI) → confirm bootstrap ran before instantiation → check get_class() of injected dependencies to see what the container actually resolved.
• Never patch vendor/. Extend or decorate. If the package requires a behavior change, upstream it or fork under your own namespace with a Composer repositories VCS entry.
• Extension points to look for: interfaces in src/Contracts/, an abstract base class intended for subclassing, and any set*()/with*() configuration methods. Those are the supported seams; direct property writes are not.
• Long-running processes. If the package caches state in a static or singleton on first use, it will behave differently under Octane, Horizon, or a long queue worker. Resolve per-job, not per-process, and add a test that runs two requests in one process.