Common Laravel Package

Getting Started

amethyst/common is a small shared-support package from the Amethyst PHP ecosystem. It ships MIT-licensed, PSR-4-autoloaded PHP code intended to be pulled in by the other amethyst-* packages rather than used as a standalone framework. With ~1 star and no known dependents, treat it as a reference library, not a production dependency you build a product around.

Minimal steps:

1. Install it alongside the Amethyst packages you actually use (installing it alone gives you little):

   composer require amethyst/common
   

   If you are pinning the rest of the stack, pin this too ("amethyst/common": "^1.0") so a surprise release cannot drift your shared primitives.

2. Read composer.json first. Confirm the php constraint, the autoload.psr-4 namespace prefix, and whether it declares any require entries. This tells you immediately whether it is dependency-free (usually a good sign for a "common" package) and which namespace to import.

3. Read src/ before README.md. There is effectively no documentation and no meaningful community footprint, so the source is the spec. Skim for the handful of classes/traits/contracts the package exposes — a "common" library of this size typically holds base exceptions, small value helpers, and interfaces shared between sibling packages.

4. Check tests/ (if present) to see intended usage; test files are usually the only examples you will get.

First real use case: you are pulling in amethyst/http, amethyst/router, or similar, and one of them type-hints against a class or interface that lives here. In that scenario your job is simply to ensure amethyst/common is installed at a compatible version and to stop your own code from re-implementing the same helper. Do not vendor-copy the classes; let Composer resolve them so the sibling packages stay interoperable.

Implementation Patterns

Let Composer resolve it transitively, and only require it directly if you touch its types. The normal workflow is: require the functional amethyst-* package you want, notice a shared class in a signature or exception hierarchy, then composer why amethyst/common to confirm which package brought it in. Requiring it explicitly is only worth it when you reference its namespace in your own code.

Wrap shared primitives behind your own seam. Because adoption is near-zero, any type you expose from this package is a type you cannot easily replace later. Import it in one adapter class rather than scattering the namespace across your codebase:

namespace App\Bridge;

use Amethyst\Common\...; // the one or two types you actually need

final class SharedPrimitives
{
    // Delegate here so a future replacement is a single-file change.
}

Use it as a consistency layer inside a monorepo. If you are building several packages that mirror the Amethyst split (http, router, config, core), a common package is the right home for cross-cutting exceptions and contracts. That is the pattern this package exists to demonstrate — copy the structure, not necessarily the code.

Integration tip: verify class existence at the boundary. When a sibling amethyst-* package type-hints a class from here, add a boot-time or CI check so a version skew fails loudly instead of at runtime:

// tests/ContractTest.php
$this->assertTrue(class_exists(\Amethyst\Common\SomeSharedType::class));
$this->assertTrue(interface_exists(\Amethyst\Common\SomeSharedContract::class));

Workflow for upgrading: bump amethyst/common in isolation, run your full suite, and diff the src/ tree between tags (git diff v1.0.0..v1.1.0 -- src/). At this project size the entire API fits on a screen, so a visual diff is a faster and more reliable changelog than release notes.

Exception mapping pattern. If the package supplies base exception types, catch your application exceptions and translate at the edges; do not let a low-traffic third-party exception hierarchy leak into your controllers or HTTP responses.

Gotchas and Tips

Maintenance risk is the dominant pitfall. One star, zero dependents, and no visible downstream users mean: no Stack Overflow answers, no third-party tutorials, and a real chance bugs stay open. Budget for the possibility that you own the fork. If the code is small enough, composer require it now and be prepared to replace it later via a Composer replace block with an in-house copy.

Vendor the license notice. MIT requires preserving the copyright and permission notice if you redistribute or fork. Do this at the moment you copy anything into your codebase, not later.

Beware the common naming trap. Packages named "common" or "core" frequently accumulate unstable, internal-facing APIs. Do not build on anything that looks like an implementation detail (concrete helpers with Internal/Abstract prefixes, things only the sibling packages call). Restrict yourself to public interfaces and exception types.

Namespace and autoload mismatches are the classic symptom when a package is this small: Class not found usually means you guessed the namespace from the repo name (amethyst-php/core) whereas the Composer package is amethyst/common. Always read autoload.psr-4 in composer.json and let your IDE confirm with composer dump-autoload -o after install.

Debugging checklist when something breaks:

• composer show amethyst/common — confirm the resolved version.
• composer why amethyst/common — confirm who pulled it in; an unexpected transitive require is a common surprise.
• composer depends amethyst/common — confirms the zero-dependents reality and warns you that nobody else is exercising this code path.
• Compare the installed src/ against the tagged release; if the repo has a stale composer.lock or untagged commits, you may not be running what you think.

Extension points are limited by design. Expect the intended extension mechanism to be composition around the package's contracts rather than subclassing its concrete classes. If you need behavior it does not offer, write a decorator implementing the same interface — that survives upgrades far better than extending a concrete class whose internals may change without notice.

Pin and lock aggressively. Given no downstream users, semantic-versioning discipline is unproven. Commit composer.lock, and treat any minor bump as a potentially breaking change until you have read the diff.

CI hygiene. Add the package's namespace to whatever static-analysis baseline you use (PHPStan/Psalm). If it ships without type declarations or docblocks, silence only that namespace and do not let its weak typing erode the rest of your analysis.