Amethyst Common Laravel Package

Getting Started

This is an internal foundation package for the Amethyst PHP ecosystem — the kind of dependency you pull in because you're building an Amethyst package, not because you want a feature for end users. Treat it as scaffolding, not an application library.

1. Install it as a dev/runtime dependency of your own package:

   composer require railken/amethyst-common
   

   Because it's the shared base layer, it will usually arrive transitively when you depend on other amethyst-php/* packages. Check composer show railken/amethyst-common to see whether it's already in your tree before requiring it explicitly.

2. Look at the source before the README. With 1 star and 0 dependents, documentation will be thin or nonexistent. Your real reference is:

   • composer.json — PHP version constraint, autoload namespace (this tells you the root namespace to use).
   • src/ — the actual class list. Expect helper classes (array/string/reflection utilities) plus base classes/traits/contracts intended for extension.
   • tests/ — the most reliable usage examples you'll get.
   • vendor/railken/amethyst-common/ locally, since Packagist/GitHub browsing will be sparse.

3. First real use case: you're writing a new Amethyst package and need to avoid re-implementing shared plumbing. The typical first step is to extend one of its base classes (or apply one of its traits) in your own package's main class, and register your package's service provider the same way the core package does. Copy the shape of an existing Amethyst package rather than inventing one — this package defines the conventions those packages follow.

Implementation Patterns

Extend, don't fork. The package exists so packages share a common ancestry. If you find yourself copying a helper or base class out of it into your own code, you're fighting the design. Extend the class or use the trait, and override only the methods you need.

Use it as the convention layer for a package. When building a new Amethyst package:

• Have your main class extend the corresponding base/abstract class from this package.
• Apply its traits for shared behavior rather than writing mixins yourself.
• Follow its service-provider registration pattern so your package boots like the rest of the ecosystem.

Lean on the helper utilities inside your own code. The array/string/reflection helpers are the lowest-risk part of the package to consume — small pure functions with obvious behavior. Prefer calling these over hand-rolling the same logic in each package, which keeps behavior consistent across the ecosystem.

Integrate via Composer, not globals. Add it as a normal require with a pinned version, and let the parent Amethyst package bring in the version it expects. If you need to support multiple versions, constrain yourself to the API surface shared across them.

Test against the actual installed version. Write your package tests to run against the concrete vendored copy of amethyst-common, so upgrades surface as failing tests rather than mysterious runtime errors. Since there's no community test suite to lean on, your tests are the compatibility contract.

Gotchas and Tips

Treat this as low-support, high-trust code. 1 star and 0 dependents means: no issue triage, no security advisories, no community answers. Pin to an exact version ("railken/amethyst-common": "1.2.3" style) and commit composer.lock. For anything long-lived, vendor the source into your repo or fork it so a deleted/rewritten upstream can't break your build.

Read the source, assume nothing about the API. Method names, signatures, and return types may change between minor versions without changelog ceremony. Verify behavior directly in vendor/ rather than trusting memory of "how these helpers usually work."

Watch the autoload namespace. The package name (amethyst-common) and the repo name (amethyst-php/core) don't match, which is a hint that the root namespace may also not match the package name. Confirm the psr-4 mapping in composer.json before writing use statements — a wrong guess gives a confusing "class not found" at runtime, not a clear error.

Service provider / registration quirks. If the package ships a service provider, it may rely on Laravel's package auto-discovery. If your consuming app has discovery disabled or is on a different framework version, you'll need to register it manually. Symptom: bindings/helpers silently missing while the classes themselves autoload fine.

Debugging checklist when something is "missing":

• composer dump-autoload after adding or updating — stale autoloaders are the most common false alarm.
• composer why railken/amethyst-common to see who actually pulled it in and at what version.
• composer show -a railken/amethyst-common for available versions if you're resolving a conflict.
• Confirm PHP version satisfies the package's constraint; older PHP versions can produce fatal errors from newer syntax rather than clean dependency failures.

Extension points are class-based, not config-based. Expect the intended customization path to be subclassing and container rebinding rather than a published config file. If you need to alter behavior, bind your subclass in the service container and override the base class binding — never edit within vendor/.

Don't expose it in your public API. Since the upstream package has no stability guarantee, avoid leaking its types in your own package's public signatures where you can help it; wrap them behind your own interfaces so you can swap the implementation if upstream goes stale.