Core Laravel Package

Getting Started

1. Confirm you actually need it directly. secretary/core is the base layer of a split monorepo (secretary/php-core on GitHub). In practice it should arrive transitively as a dependency of the higher-level Secretary packages. Before running composer require, check with composer why secretary/core on an installed sibling package — if it's already there, you only need it in require if you are writing code against its contracts.
2. Read the split repo's composer.json first. The repo is a [READ-ONLY] subtree split, so the README is often thin. The autoload block is the authoritative source of the namespace(s) you will be importing; do not guess namespaces from the package name (secretary/core ≠ Secretary\Core\... necessarily).
3. Treat tests/ as the documentation. With 2 stars and no dependents, the test suite is the most reliable description of behaviour and intended usage you will get.
4. First use case: install it, dump an optimised autoloader, and exercise the smallest public surface in isolation before wiring it into a framework:

composer require secretary/core
composer dump-autoload -o
composer show secretary/core    # version, deps, autoload paths

require __DIR__ . '/vendor/autoload.php';

// Reflect over the package's own namespaces to see exactly what is exposed
$prefixes = require __DIR__ . '/vendor/composer/autoload_psr4.php';
$core = array_filter($prefixes, fn ($p) => str_contains($p[0], 'secretary/core'), ARRAY_FILTER_USE_KEY);
var_dump($core);

Get one core object instantiated and round-tripped through a unit test of your own before adding any sibling package on top.

Implementation Patterns

• Depend on the abstract layer. The point of a *-core split is that the concrete, opinionated packages sit above it. Type-hint against the core's interfaces/contracts in your own services, and let the higher-level packages supply implementations. That keeps you insulated if the concrete packages churn.
• Bind via the container, don't new up the graph. In Laravel, register core contracts in a service provider and resolve them; the core library itself is framework-agnostic, so the wiring responsibility lands on you. Keep that wiring in one provider rather than sprinkled through controllers.
• Extend, don't fork. Core libraries in monorepo splits are typically designed for subclassing base classes and implementing interfaces. If you find yourself copying src/ into app/, you've picked the wrong extension point — check for protected methods, abstract classes, or event/hook seams first.
• Pin the whole family to one minor. When you use secretary/core alongside any sibling secretary/php-* package, constrain them together ("secretary/core": "^0.x" matching the sibling's requirement). Inter-package APIs in split monorepos drift across minors far more readily than in a single large package.
• Test against your own fakes. Because there are effectively no third-party consumers, there is no ecosystem of established test doubles. Write your own stubs against the core interfaces and keep them in tests/Support/ so a future upgrade is a single-file change.
• Use composer why-not and composer depends during upgrades rather than reading changelogs — the split repo's history is a mirror and its release notes are often just the monorepo commit titles.

Gotchas and Tips

• READ-ONLY means read-only. Pull requests and issues raised against secretary/php-core will usually be closed or ignored; the fix has to land in the monorepo and then be re-split. If you need a patch, use a vcs/path repository override or a Composer patch plugin rather than expecting a merged PR, and budget for carrying it.
• Split repos lag. Tags can appear in the split after the monorepo, and occasionally a bad subtree split drops a commit. If a documented feature is missing, verify against the monorepo commit, not just the tag you installed.
• Adoption risk is real. 2 stars and 0 dependents means: no Stack Overflow answers, no blog posts, no third-party security advisories. Wrap the library behind your own narrow interface so you can swap it out, and avoid spreading its types across your domain layer.
• 0.x versioning. Anything below 1.0 permits breaking changes in a 0.x bump under SemVer. Use ~0.x.y if you want stability, and commit your composer.lock.
• Namespace/package mismatch. The package is secretary/core but the repository is php-core. Tooling that maps package name → repo name (some CI badges, dependency scanners, composer outdated -D cross-referencing) will mislead you; always confirm via composer show -a secretary/core for the real source URL.
• Autoload traps. Classmap-authoritative deployments (composer install --classmap-authoritative) combined with a stale vendor dir is the usual cause of "class not found" reports on small packages with few files. Run composer dump-autoload -o after any path or vcs override.
• Debugging recipe: composer why secretary/core (who pulled it in), composer why-not secretary/core 0.x (what blocks the upgrade), then git log --oneline inside vendor/secretary/core if it was installed from source — the split history shows which monorepo commits actually touched the core.
• Extension points to inspect first: the src/ root for anything named Contract, Interface, Abstract*, or Concern/Trait, plus any events/hooks directories. Those are the seams the maintainers intended; everything else is incidental API.