Core Laravel Package

Getting Started

Start with the package documentation and config/gcego.php after publishing config:

composer require gcego/core:^1.0
php artisan vendor:publish --tag=gcego-config

If Packagist indexing is not available yet, install from the VCS repository:

composer config repositories.gcego-core vcs https://github.com/GceGO/core.git
composer require gcego/core:^1.0

Laravel auto-discovers the Core provider. Confirm requirements before adopting: PHP 8.3+ (below 9.0), Laravel 13, Composer 2.2+.

Look first at:

• The published gcego config for package, dependency, extension, and capability settings.
• The gcego:plan command for a read-only startup preview.
• The gcego:diagnose command for operational checks.
• The linked docs and changelog for lifecycle event names and diagnostic code references.

First practical use case: install in a staging environment, run php artisan gcego:plan before enabling Admin Studio packages, then run php artisan gcego:diagnose to validate startup health. Use gcego:diagnose --json --strict in CI or deployment checks once the package graph is stable.

Implementation Patterns

Treat package registration as declarative configuration. Register packages, required and optional dependencies, version constraints, and extension capability prerequisites before startup. The kernel coordinates dependency-ordered startup, so dependency metadata should be the source of truth rather than ad hoc provider boot ordering.

Use gcego:plan as a preflight step:

php artisan gcego:plan

Run it when adding packages, changing dependency versions, enabling extensions, or modifying capability requirements. Because the preview is read-only, it is suitable for staging and CI diagnostics before deployment.

Use lifecycle events and initialization hooks for integration work. Keep initialization hooks retry-safe and idempotent: the release notes call out retry-safe initialization, so hooks should tolerate repeated execution and avoid non-reversible side effects.

Use diagnostics as the operational interface:

php artisan gcego:diagnose
php artisan gcego:diagnose --json --strict

Prefer stable diagnostic codes over message text when building alerting, dashboards, or deployment gates. Use the public health summary for broadly shareable health checks, and the detailed diagnostics for operators. Enable detailed profiling only when investigating startup performance, since it is opt-in.

For extension development, declare capability prerequisites alongside the extension and verify them through the plan output. Optional dependencies should be modeled explicitly so startup behavior remains predictable when they are absent.

Gotchas and Tips

• Package registration closes before dependency resolution and initialization hooks. Register packages during the registration phase; late dynamic registration from an initialization hook will likely be ignored.
• Dependency order is resolved by the kernel, but incorrect or missing dependency metadata will surface as startup diagnostics. Fix declarations rather than relying on service provider ordering.
• Version compatibility and extension capability prerequisites are enforced. Run gcego:plan after any version bump or extension enablement.
• gcego:diagnose --strict is appropriate for CI and operational gates, but verify its strictness semantics in your environment before making it a hard deployment blocker.
• Diagnostics include redaction and a separate public health summary. Do not assume detailed diagnostic output is safe to expose publicly; use the health summary for external consumers.
• Detailed profiling is opt-in. Keep it disabled by default in production unless actively debugging startup latency.
• The package requires PHP 8.3+ and Laravel 13. Pin Composer and PHP versions in CI to avoid environment drift.
• Packagist indexing may lag for a new release. The GitHub VCS repository path is a valid fallback, but pin to ^1.0 and review the changelog when upgrading.
• Use the stable diagnostic codes for runbooks and alert mapping; messages and remediation text may be more descriptive but codes are the durable integration point.
• Publish and review the config before customizing startup behavior. Keeping configuration changes small and validating with gcego:plan reduces startup surprises.