Core Bundle Laravel Package

Getting Started

Read the source before you run composer require. There is no docs site, no changelog discipline, and no community tutorial layer for smart-core/core-bundle — the repository itself is the documentation. Open these files in this order:

1. composer.json — the single most important file. It tells you the actual target framework (laravel/framework vs symfony/*), the PHP constraint, and whether a Laravel bridge exists. The package name says "bundle" and the namespace says CoreBundle, which is Symfony convention, while the description claims Laravel discovery. Resolve that contradiction before anything else.
2. src/ — locate the base service provider and any Contracts/ directory. These are the two things downstream "modules" are meant to extend, so they define how you will actually use the package.
3. config/ — the publishable config tree. This is where the "sensible defaults" live.
4. README.md and CHANGELOG.md — expect a deprecation banner and little else.

Install it into a throwaway app first, not your production skeleton:

composer require smart-core/core-bundle

Confirm Composer actually resolves against your PHP and framework versions:

composer why-not smart-core/core-bundle
composer show smart-core/core-bundle

Then verify discovery/boot:

php artisan package:discover --ansi   # Laravel path
php artisan about                      # confirm the provider registered
php artisan vendor:publish --provider="SmartCore\CoreBundle\..."   # inspect publish tags

Your first use case is not "build a feature." It is a five-minute fit check: boot the provider, publish the config, and look at the base provider class to see whether downstream packages are expected to extend it. If the provider boots and you can see the bindings in the container, you have the full surface you need to evaluate. If the provider references Symfony kernel/Bundle classes that Laravel's container does not supply, stop — that is the answer, and it is "no."

Day-to-day, the package is meant to be the seam your own modules hang off: a single entry point that registers your feature providers, merges their config, and gives you shared base classes so modules stay out of app/. That is a genuinely good pattern. It is also a pattern you can reproduce in roughly fifty lines of first-party code, which should be your benchmark for whether the dependency earns its place.

Implementation Patterns

Extend the base provider rather than writing raw providers. The intended daily workflow is that each Smart Core module (yours or upstream's) declares a provider that inherits the bundle's base class, so registration, config merging, and resource loading are handled uniformly:

namespace App\Modules\Billing\Providers;

use SmartCore\CoreBundle\Providers\BaseServiceProvider;
// verify the real FQCN in src/ — do not copy this from a blog post

class BillingServiceProvider extends BaseServiceProvider
{
    protected function bootModule(): void
    {
        $this->loadMigrationsFrom(__DIR__.'/../database/migrations');
        $this->loadViewsFrom(__DIR__.'/../resources/views', 'billing');
    }
}

Register module providers in one place — normally bootstrap/providers.php in Laravel 11+, or config/app.php on older versions — and keep that list short and explicit. If the bundle offers auto-discovery of modules, verify what it scans (composer.json extra.laravel.providers, a config array, or a directory glob) and prefer the explicit list; auto-discovery via globs is the usual source of "works on my machine, provider missing in CI" bugs after a cache clear.

Bind against contracts, not the bundle. The description pitches "shared contracts and base classes for downstream bundles." That is the correct integration posture: your application code should type-hint your interfaces, with the bundle (or your adapter) as one implementation. This is the pattern that makes the eventual removal a config swap instead of a refactor:

// app/Contracts/ModuleRegistry.php  — owned by you
interface ModuleRegistry { public function all(): array; }

// A binding in your own AppServiceProvider, pointing at the bundle now
$this->app->singleton(ModuleRegistry::class, BundleModuleRegistry::class);

When you retire the bundle, you re-point one binding.

Configuration belongs in config/smart-core.php, published and committed. Publish once, commit the file, and treat the package's config as an upgrade surface you will re-diff. Do not read package internals directly from env() in module code — merge through the published config so overrides are visible in one file. Keep environment-specific values (cache TTLs, feature flags) in your published config referencing env(), not in the vendor tree.

Keep module concerns out of app/. The bundle's value proposition is separation. In practice that means: module code lives under app/Modules/{Name}/ or packages/{name}/, each module owns its provider, config, migrations, and views, and app/ contains only application composition (bindings, provider list). Enforce it with a code-review convention or a PHPStan rule, because nothing technical stops a developer from dropping a billing model into app/Models and quietly defeating the structure.

Test the seam, not the bundle. Write one integration test that boots the provider and asserts your container bindings resolve. Everything else — module behaviour, business rules — is tested through your own classes. Laravel's orchestra/testbench is the right harness if you are building downstream packages that depend on this one; it gives you a booted app without a full project.

Pin precisely and vendor if you must continue. If this ends up in a real codebase, pin to a tagged commit or short hash, not a floating ^1.0, and mirror it into a private repository (Satis, Private Packagist, or a vcs entry pointing at your fork). Upstream is deprecated, so your "latest version" must be a version you control:

{
  "repositories": [{ "type": "vcs", "url": "git@internal:acme/core-bundle.git" }],
  "require": { "smart-core/core-bundle": "dev-internal as 1.0.0" }
}

Gotchas and Tips

The deprecation notice is the headline, not a footnote. Everything below is secondary to this: the package receives no patches, so any bug or framework-compat break you hit becomes your backlog item immediately. Plan the exit before you plan the integration.

Framework ambiguity will bite you first. "Bundle," CoreBundle, and Symfony-style kernel assumptions do not map onto Laravel's container without glue. If composer require resolves but the provider fatals on boot, check whether it type-hints Symfony's ContainerInterface, Kernel, or Bundle base classes. A Laravel adapter layer on top of a deprecated dependency is the worst of both worlds — extra code you own to reach code nobody maintains.

Zero dependents means zero field reports. You will not find the bug you are about to hit on Stack Overflow, and there are no community compatibility patches for your PHP version. Budget for reading source. When something breaks, git log -p on the affected file is your only changelog.

Discovery and config caching hide registration bugs. After adding or renaming a provider, run php artisan optimize:clear (or config:clear + cache:clear + package:discover) before concluding the provider is not registering. The classic symptom — works in php artisan tinker, missing in queue workers — is a stale cached provider manifest.

Publish tags are not guessable. If vendor:publish does nothing, list the actual tags rather than assuming: php artisan vendor:publish --provider="..." with no tag shows the available groups. Committing a published config that came from a different tag than you think is a common silent misconfiguration.

Provider ordering matters if the base provider registers singletons. Module providers that depend on a binding from the core provider must be registered after it. With auto-discovery the order is effectively arbitrary; with an explicit array in bootstrap/providers.php it is deterministic. Prefer the explicit array.

Do not let the composite score substitute for due diligence. An opportunity: 9.65 alongside zero stars, zero dependents, and a deprecation banner is a scoring artifact, not a signal of fitness. If a stakeholder cites the score, show them the deprecation line in the README.

Treat the source as a reference implementation. The highest-value use of this repository is reading how it wires providers, merges config, and structures contracts — then writing a small first-party equivalent behind your own interfaces. That version you can support, version, and instrument. If you do adopt, do it as a pinned internal fork with a named owner, a regression test around the specific behaviour you depend on, and a scheduled removal date — and add it to your dependency inventory so it shows up in SBOM and upgrade reviews before a framework bump forces the issue mid-release.