Core Laravel Package

Getting Started

yarunoka-dev/php-core is a spec-driven core library: its public API tracks an external specification rather than pure SemVer convenience. Release 1.3.0 aligns the package with spec 1.1 and is flagged as a breaking change, so treat it as a new major for practical purposes.

Minimal steps:

composer require yarunoka-dev/php-core:^1.3
php artisan vendor:publish --tag=php-core-config

Where to look first, in this order:

1. README.md — install and the canonical “hello world” usage.
2. UPGRADING.md / the spec 1.1 changelog — 1.3.0 is a spec-alignment release; the diff between 1.2.2 and 1.3.0 is the real upgrade guide. PR #56 (Follow the spec 1.1 release) is the authoritative change list.
3. src/Contracts/ — the interfaces you should bind against rather than concrete classes.
4. config/php-core.php — the package’s knobs and defaults.

First use case: bind the package’s entry point in a small service provider and call it from a console command before wiring it into HTTP controllers.

// app/Providers/PhpCoreServiceProvider.php
public function register(): void
{
    $this->app->bind(
        \Yarunoka\PhpCore\Contracts\CoreInterface::class,
        \Yarunoka\PhpCore\Core::class,
    );
}

Then exercise it from php artisan tinker or a throwaway command, so you see the actual return types under spec 1.1 before building on top of them.

Implementation Patterns

Wrap, don’t sprinkle. Keep the package behind one application-level adapter (App\Support\Core\CoreAdapter). When spec 1.2 lands (or a 1.3.x patch adjusts behaviour), you change one class instead of grepping the codebase.

final class CoreAdapter
{
    public function __construct(private CoreInterface $core) {}

    public function handle(Input $input): Result
    {
        // translate your domain DTOs <-> package types here
    }
}

Bind interfaces in a dedicated provider. Register the package bindings in one provider registered early, and inject CoreInterface everywhere else. This is your main insulation against breaking releases.

Config over constructor arguments. Drive behaviour through config/php-core.php (published) and environment variables rather than instantiating the core with hard-coded options. This keeps queue workers and Octane processes consistent.

Use it inside jobs and commands, not just controllers. The core is stateless enough to be resolved per job. If you queue work that touches the package, resolve it inside handle() (not in the constructor) to avoid serialization problems and stale config in long-lived workers.

Testing pattern. Fake at your adapter boundary, not at the package boundary:

$this->mock(CoreInterface::class, function ($mock) {
    $mock->shouldReceive('handle')->once()->andReturn(new Result(...));
});

Add a thin “spec conformance” test suite that runs the package’s own fixtures against your adapter; when 1.3.x patches arrive you’ll know immediately whether behaviour moved.

Upgrade workflow for 1.2.x users.

git switch -c chore/php-core-1.3
composer require yarunoka-dev/php-core:^1.3 --update-with-dependencies
php artisan config:clear && php artisan cache:clear
vendor/bin/phpunit
vendor/bin/phpstan analyse

Then grep for every removed/renamed symbol called out in the spec 1.1 diff, and check return types — spec alignments usually change shapes (return objects, nullable values, exception types) more than names.

Pin deliberately. Because 1.3.0 is breaking inside a 1.x line, use ~1.3.0 or an exact pin in composer.json, and let Renovate/Dependabot open a PR rather than floating ^1.0.

Gotchas and Tips

• Breaking change in a minor release. 1.3.0 following 1.2.2 with a breaking change is a SemVer warning sign. Read the compare link (1.2.2...1.3.0) and PR #56 before upgrading; don’t assume composer update is safe across 1.2 → 1.3.
• Spec-first, Laravel-second. The package’s changelog is the spec’s changelog. If you rely on behaviour the spec 1.1 changed, your tests are the only thing that will catch it — the package won’t warn you at runtime.
• Config cache. After upgrading, run php artisan config:clear (and optimize:clear in deploy scripts). New 1.3 config keys silently fall back to defaults if a cached config from 1.2 is in play.
• Long-lived workers. Under Octane/queue workers, singleton bindings can hold pre-upgrade assumptions. Prefer bind over singleton for anything holding per-request state, and restart workers as part of the deploy.
• Static analysis is your upgrade test. Larastan/PHPStan at a decent level will surface most signature drift from the spec 1.1 alignment faster than runtime tests will.
• Extension points. Prefer implementing the package’s contracts and registering them via container bindings over subclassing concrete classes — spec-alignment releases are far more likely to change concrete internals than the interfaces.
• Debugging. Log the resolved spec/package version at boot (composer show yarunoka-dev/php-core) in staging. When behaviour differs between environments, the version skew — not your code — is usually the cause.
• Watch the patch line. After a spec-alignment release, expect 1.3.x patches that fix conformance edge cases. Subscribe to the repo’s releases; those patches are usually low-risk and worth taking quickly.