Getting Started

clean/phpatlas has zero public signal (0 stars, 0 dependents, score 0), so treat this as an unreleased-or-abandoned package until you prove otherwise in your own environment. The first "getting started" task is not wiring it up — it's vetting it.

Verification checklist before you write a single line against it:

Confirm the repository resolves and the composer.json is valid:
```
composer show clean/phpatlas --all
```
Look for require.php, require.laravel/framework/illuminate/*, a license, and a suggest/autoload section. A missing license or an unpinned Laravel constraint is a stop sign.
Install in a throwaway app first, not your main branch:
```
composer require clean/phpatlas --dev
```
Read src/ and README.md before anything else. With no dependents, the README and the service provider are your only documentation. Grep for the service provider and check extra.laravel for auto-discovery:
```
grep -R "extra" -A5 composer.json
grep -R "ServiceProvider\|Facade" src/
```
Check for a published config and commands — that tells you the intended surface area:
```
grep -R "publishes\|commands(" src/
```

Where to look first: the package's service provider (what it binds into the container), then any Console/Commands directory (what it's meant to do), then its config file. Those three files tell you 90% of the integration story.

Probable first use case: given the clean/ namespace and the atlas name, this most plausibly targets Clean Architecture boundary mapping/analysis (an "atlas" of class dependencies used to enforce layer rules) or an Atlas data-mapper wrapper. Do not assume — read src/ and confirm which before designing around it. If neither matches, the name is misleading and the package may be a personal experiment.

If it does analyze dependencies, the intended entry point is almost certainly an artisan command:

php artisan list | grep -i atlas

Implementation Patterns

These patterns assume you've completed verification above and the package does something useful. Adapt to whichever behavior the source actually implements.

Pattern 1 — Architecture gate in CI (if it's an analyzer)

The highest-leverage day-to-day use is turning the package into a CI gate that fails builds when Clean Architecture rules are violated (e.g., Domain importing Infrastructure, or a controller reaching into a repository).

# .github/workflows/architecture.yml
- name: Atlas boundary check
  run: php artisan atlas:check --fail-on-violation

Keep the rule set (allowed edges between layers) in version control, not in the package defaults, so the team can review changes to the boundaries like code. If the package exposes a config file, publish it and commit it:

php artisan vendor:publish --provider="Clean\PhpAtlas\..." --tag=config

Pattern 2 — Local pre-commit/analysis loop

Run it locally before pushing, ideally wrapped in a Composer script so it's discoverable:

"scripts": {
  "atlas": "php artisan atlas:check --format=table",
  "check": ["@atlas", "@test"]
}

This is the "day-to-day leverage": the tool shifts architecture violations from code review to a fast local feedback loop.

Pattern 3 — Wrapping it behind your own abstraction

Because the package is unmaintained in all likelihood, do not scatter its classes across your app. Bind its surface behind one adapter:

namespace App\Support\Architecture;

interface BoundaryChecker
{
    public function check(string $path): array; // returns violations
}

final class AtlasBoundaryChecker implements BoundaryChecker
{
    public function check(string $path): array
    {
        // call clean/phpatlas here and translate its output
    }
}

Then inject BoundaryChecker via a service provider. If you later swap to deptrac, PHPArkitect, or PHPStan layer rules, only the adapter changes.

Pattern 4 — If it's an Atlas data-mapper wrapper

If the source shows Atlas\Orm\Atlas usage, the day-to-day pattern is one mapper per aggregate, registered in a repository:

final class UserRepository
{
    public function __construct(private Atlas $atlas) {}

    public function byId(UserId $id): ?User
    {
        return $this->atlas->fetchRecord(User::class, (string) $id);
    }
}

Keep Atlas out of your domain layer — inject the repository, not the Atlas instance, into domain services.

Pattern 5 — Baseline-and-ratchet adoption

Whatever the tool reports, adopt it with a baseline file so existing violations don't block the team, then forbid new violations. Most architecture tools have or can be given a baseline; if not, commit the current output and diff against it in CI. This is the standard incremental-adoption playbook and works regardless of the tool.

Gotchas and Tips

Risk and maintenance

0 stars / 0 dependents is a red flag, not a footnote. Assume no upstream support, no security patches, no Laravel upgrade path. Pin an exact version ("clean/phpatlas": "1.2.3", not ^1.0) and record the commit hash you audited.
Check the last commit date and open issues before committing. If the repo has been dormant through several Laravel majors, expect auto-discovery to break on current Laravel (service provider register/boot signatures changed, Illuminate\Contracts moved).
Confirm the license. A missing or restrictive license is a legal blocker for commercial use — resolve it before it ends up in production.

Laravel integration quirks

Auto-discovery is invisible until it fails. If composer.json has no extra.laravel.providers, you must register the provider manually in bootstrap/providers.php (Laravel 11+) or config/app.php (10 and below). Mismatched assumptions here are the #1 "package installed but nothing happens" cause.
Config caching bites analyzers. If the package reads a published config, php artisan config:cache freezes it. Always php artisan config:clear after editing the ruleset, and in CI generate the cache explicitly rather than relying on a previously-cached config.
Facades hide the binding. If a facade alias is hard-coded (Atlas::), remember php artisan about won't show it and IDE autocompletion will be missing without the _ide_helper entries. Prefer resolving the underlying contract in your adapter.

Debugging

Start with php artisan tinker and app(WhateverTheProviderBinds::class) to confirm the binding resolves. "Class not found" after a successful composer require almost always means the provider never registered.
If it's a command that produces analysis, run it with the most verbose flag (-vvv) and dump raw output before you trust the exit code — early-stage packages often return 0 even on violations.
For a mapper (Atlas) package, turn on query logging (DB::listen(...)) in a test to see exactly what SQL the mapper emits; you'll catch N+1s and unexpected SELECT *s immediately.

Extension points

Prefer the package's published config and events (grep for event(, Event::, or dispatch() over monkey-patching. If there are no events and no interfaces to bind against, that's a sign the package was never designed for integration — lean harder on the adapter pattern above.
If it registers its own container keys, alias them in your provider so your app depends on your names, not the package's, insulating you from a future swap.

Bottom line: treat clean/phpatlas as an unvetted, likely-abandoned dependency. Prove what it does by reading src/ and running it on a throwaway checkout, wrap it behind a single adapter, pin the version, and only reach for it if it saves you more than the equivalent ten lines of deptrac/PHPStan config would. For most teams the opportunity-cost calculation here favors a maintained alternative.

Phpatlas Laravel Package