Core Laravel Package

Getting Started

• Install on a branch with composer require runn/core, then check composer.json for the PHP constraint and PSR-4 namespace (Runn\Core\...). Pin the exact version you validate.
• Look first at vendor/runn/core/README.md, composer.json, src/, and tests/. With a small, low-adoption core library, the tests are often the most reliable API contract.
• Identify the primitives you will actually use before adopting it broadly: base object/DTO helpers, collection/typed-collection classes, config/data containers, casting or serialization helpers. Confirm exact class names in the installed version.
• First use case: choose one local pain point in a Laravel app—for example, an ad-hoc associative array passed through a service, or a list that needs type enforcement—and model just that case with a small Runn object or collection. Map it to/from request data or Eloquent at the boundary. Do not start by converting the whole application.
• If you need shared configuration or factories, bind them manually in an AppServiceProvider; do not assume Laravel package auto-discovery.

Implementation Patterns

• Use Runn objects as boundary DTOs/commands. Keep controllers thin: validate request data with Laravel, construct a small Runn-backed object or collection, pass it into a service/handler, and map to Eloquent only in the repository layer.
• Prefer typed collections for domain lists. Subclass the package collection for things like order lines, roles, or tags, enforce the element type at construction/addition, and avoid passing raw arrays deeper into the domain.
• Treat config/data containers as injected dependencies. Hydrate them from Laravel config arrays in a service provider, bind them as singletons where appropriate, and inject them into services. Avoid reading env() or global state inside core objects.
• Keep serialization in application code. Add explicit toArray()/fromArray() adapters or Laravel resources instead of relying on magic object behavior for JSON, queues, sessions, or database casts.
• Wrap the package behind a small interface when it touches core domain code. For example, expose your own UserCollection or UserPayload contract and let the Runn implementation sit behind it. This keeps replacement/forking cheap.
• Integrate manually with Laravel. Expect no service provider, facade, or auto-discovery. Register bindings yourself, and test config caching, queue serialization, and session storage if any Runn objects cross those boundaries.
• Test the seams. Unit-test custom subclasses, collection type enforcement, and mapping to/from Eloquent. Use the package’s own tests as behavioral examples when documentation is thin.

Gotchas and Tips

• License: LGPL-3.0 is not the same as MIT. If you distribute the application, review obligations around modification, relinking, and source availability with legal/engineering before making it foundational.
• Adoption risk: 32 stars and 0 dependents means little community support. Pin the version, keep it behind adapters, and be prepared to fork or replace it. Check maintenance activity before relying on it for core domain primitives.
• Magic properties and PHP versions: core “std object” style helpers often rely on __get/__set or dynamic properties. Test on your PHP version, especially PHP 8.2+, and expect weaker IDE/static-analysis support. Prefer declared properties in your own subclasses.
• Type coercion and nulls: test null, '', 0, and array-vs-scalar inputs explicitly. Collection and casting helpers may be looser than Laravel’s validation layer.
• Collection keys: confirm whether keys are preserved or reindexed before relying on them for ordering or identity. Normalize with array_values() when order matters.
• Serialization boundaries: do not put Runn objects into cached config, session payloads, queue jobs, or Eloquent casts until you have tested round-tripping. Convert to plain arrays at those edges.
• Extension points: prefer small subclasses and composition over deep inheritance. If the package exposes protected type/validation hooks, use them for invariants, but avoid overriding internal methods that may change between versions.
• Debugging: start from the package tests and a failing local test. Run composer dump-autoload after namespace changes, and confirm you are importing the versioned Runn\Core\... class rather than a similarly named local class.
• Do not leak package types into public APIs unless you are committed to it. Public methods returning Runn collections/objects make later replacement harder.