Core Laravel Package

Getting Started

joy/core is the shared foundation for the joy/* package family. It is not a feature package; it exists so that every other joy/* package can rely on the same config shape, helper functions, and base abstractions. Treat it as infrastructure, not application code.

Minimal steps to get productive:

1. Install it alongside at least one feature package. joy/core on its own gives you almost nothing to call — its value is realized when a sibling package (e.g. joy/* modules that depend on it) is present.

   composer require joy/core
   

2. Confirm auto-discovery is working. Laravel should pick up the service provider via composer.json extra.laravel.providers. If not, register it manually in config/app.php:

   Joy\Core\JoyCoreServiceProvider::class,
   

3. Publish and inspect the config first. This is the single highest-leverage thing you can do in the first 10 minutes:

   php artisan vendor:publish --provider="Joy\Core\JoyCoreServiceProvider"
   

   Read the published file end-to-end. The keys in this file are the contract every joy/* package reads from, so understanding them is prerequisite to understanding any sibling package.

4. Look for the helpers autoload entry. Check the package's composer.json for a "files" array. That's where global helper functions live, and it tells you the real public API surface faster than reading the service provider.

5. First use case: wire the package into a small feature package you're evaluating. For example, if joy/core provides a base repository/contract that a joy/* data package consumes, bind that contract in a service provider and see it resolve. That validates both packages in one pass.

Because the repo has ~2 stars, 0 dependents, and a last release in September 2023, do not assume the docs are complete. The src/ directory and the published config are the actual documentation.

Implementation Patterns

Config-first consumption. The most reliable pattern with a glue package like this is to always resolve settings through config('joy.*') (or whatever namespace it publishes under) rather than hardcoding values that the package already exposes. When a sibling joy/* package later adds a knob, your code already reads from the shared tree.

$driver = config('joy.driver', 'default');

Extend, don't fork. joy/core almost certainly ships base classes or traits meant to be inherited by downstream packages. When you build your own module in the same family, extend those bases instead of reimplementing — that's the entire reason the package exists.

use Joy\Core\Support\BaseService; // adjust to actual namespace

class InvoiceService extends BaseService
{
    // inherit the shared boot/config wiring
}

Bind contracts in your own provider. If joy/core defines interfaces, bind the concrete implementations in an application-level service provider, not in the package's own provider. This keeps the shared package untouched and makes testing trivial:

public function register(): void
{
    $this->app->bind(
        \Joy\Core\Contracts\Formatter::class,
        \App\Support\MyFormatter::class
    );
}

Grouped config publishing. When several joy/* packages are installed, publish all tags at once to avoid a scattered config directory:

php artisan vendor:publish --tag=joy-config

If the package doesn't tag its publish group, use --provider per package.

Wrap helpers behind your own facade. Global helper functions in the "files" autoload are convenient but untestable in isolation. If your application relies on them heavily, wrap the ones you actually use in a small facade or service so you can mock them in unit tests:

class JoyFacade extends \Illuminate\Support\Facades\Facade
{
    protected static function getFacadeAccessor() { return 'joy.core'; }
}

Environment separation. Because this config is shared across the whole family, override per-environment via .env keys that the config file reads through env(). Never edit the vendor config directly — publish, then edit the published copy.

Version pinning. With the latest release in September 2023, pin the version explicitly in composer.json and commit composer.lock. The package is not actively maintained enough to trust floating constraints:

"joy/core": "^1.0"

Gotchas and Tips

Zero dependents means near-zero battle-testing. You are effectively the QA team. Before adopting in production, run the full test suite of your app after install and verify the service provider doesn't register conflicting singletons or override framework bindings.

The package is a coupling layer. joy/core is designed to be depended on by joy/* packages, not by your app directly. If you find yourself calling its helpers everywhere, you've inverted the intended dependency direction. Consider whether you should depend on a feature package instead and let it pull core transitively.

Config publish collisions. Multiple joy/* packages may each publish into the same config/joy.php file or the same tag. Publishing twice can silently overwrite earlier changes. Publish once, diff against what you had, and merge manually.

Stale since 2023. Check the PHP and Laravel version constraints in composer.json. If they cap at Laravel 10, you may hit resolution conflicts on Laravel 11+. Work around with --ignore-platform-reqs only in local dev — never in CI.

Namespace discovery is not guaranteed. With low star counts, the extra.laravel.providers block may be missing or malformed. If helpers or config aren't loading, that's the first thing to inspect. Manually listing the provider is a safe fallback.

Debugging helper conflicts. If a helper function name in the "files" autoload collides with one from another package or your own app/helpers.php, you get a fatal redeclare error at boot with a confusing stack trace. Search the vendor tree for the function name:

grep -rn "function yourHelperName" vendor/

Extension points are the real value. The most durable thing to extract from this package, even if you drop it later, is its base class design — the way it structures service providers, config merging (mergeConfigFrom), and publishes assets. Copy that pattern into your own internal glue package rather than depending on a two-star, one-year-stale dependency.

Testing. Because the package provides global state (config, helpers), reset state between tests. If it registers singletons, use RefreshDatabase plus a fresh application bootstrap per test class rather than per test method, or bind mocks before the provider boots.

Fork if you need to maintain it. With 0 dependents and no releases in over a year, the practical advice is: if you build on this, vendor it (path repository) so you can patch it yourself without waiting upstream. An abandoned core package is a liability in a supply chain.