Crater Laravel Package

Getting Started

Crater is an application, not a drop-in package — composer require bytefury/crater into an existing Laravel app is not a supported workflow. Treat it as one of three things: a self-hosted SaaS alternative, an API backend you consume, or a fork you own.

Start by cloning and running it locally to see the shape of the thing:

git clone https://github.com/bytefury/crater.git
cd crater
composer install
cp .env.example .env && php artisan key:generate
# edit .env: DB_*, APP_URL, MAIL_*
php artisan crater:install      # interactive installer: DB, admin user, sample data
php artisan storage:link
npm install && npm run dev      # Vue SPA assets
php artisan serve

Read these first, in order:

1. routes/api.php — the entire surface area is API-first; every UI action is an endpoint.
2. app/Http/Controllers/API/V1/ — one controller per resource (Invoice, Estimate, Payment, Expense, Customer, Item, Tax…).
3. app/Models/Invoice.php + InvoiceItem — the invoice/line-item/currency relationships drive most customizations.
4. .env.example — the real config reference; there is no published config/crater.php worth reading.

First use case: don't rebuild invoicing. If you need "customers, invoices, PDFs, payments, recurring billing" in a Laravel product, point your app at a self-hosted Crater instance's REST API and move on. Log in via POST /api/v1/auth/login (email, password, device name), take the returned token, send Authorization: Bearer <token> thereafter.

Second use case: fork it and white-label. Change the logo/colors in the Vue assets, the PDF template in resources/views/app/pdf/, and the mail templates — this is a 1–2 day job versus months to build.

Implementation Patterns

Consume the API instead of embedding the code. This keeps your codebase free of AGPL obligations (the license triggers on distribution and on network use of modified source, not on calling a separate service over HTTP — but confirm with counsel for your case). A thin client:

class CraterClient
{
    public function __construct(
        private string $baseUrl,
        private string $token,
    ) {}

    public function createInvoice(array $payload): array
    {
        return Http::withToken($this->token)
            ->baseUrl($this->baseUrl.'/api/v1')
            ->acceptJson()
            ->post('invoices', $payload)
            ->throw()
            ->json();
    }
}

Cache the token (it survives until revoked/logout) rather than logging in per request; a login per job will thrash the personal_access_tokens table and slow bulk syncs.

Mirror-and-sync pattern. Keep your own customers / invoices tables with a crater_id column. Push creates, pull status changes (paid, partially_paid) on a schedule. Crater emits no webhooks in the 2022 codebase — polling GET /api/v1/invoices?status=paid&updated_at=... (or just filtering client-side) is the only option without a fork.

Fork-and-extend pattern. Add your endpoints the Laravel way — new controller in app/Http/Controllers/API/V1/, a FormRequest, a route in routes/api.php inside the authenticated group, and a policy/resource. Reuse the existing Invoice model rather than duplicating money/tax logic. For side effects (e.g. sync to your CRM when an invoice is paid), prefer an observer or model event over editing controllers — controllers are long and it's easy to miss a code path.

Scheduled work is the package's spine. Recurring invoices and payment reminders don't run on their own; you need a cron entry:

* * * * * cd /path/to/crater && php artisan schedule:run >> /dev/null 2>&1

Plus a queue worker (QUEUE_CONNECTION=database is fine) or emails and PDF jobs silently pile up. Inspect app/Console/Kernel.php for the exact command names before assuming.

Template-level integration. For PDFs, override the Blade views under resources/views/app/pdf/ in your fork — this is far easier than trying to restyle via API data, because the PDFs are rendered server-side with the full model graph, not from the JSON payload.

Gotchas and Tips

Staleness is the headline risk. Last release March 2022: Laravel 8, PHP 7.4/8.0, Vue 2, and a webpack/Laravel Mix toolchain are all EOL. On a modern host you'll hit PHP 8.1+ deprecations, npm install peer-dep explosions, and Composer audit noise. Budget a dependency-upgrade sprint before you depend on it, or pin it in Docker with an older PHP image (php:8.0-fpm) and isolate it.

AGPL-3.0 is not MIT. Modifying Crater and exposing it to users over a network obligates you to offer the modified source. Internal-only, unmodified self-hosting is low-risk; white-labeling for customers is not. This is the single most common surprise for teams that assume "open source invoicing = free to embed."

Currency conversion breaks quietly. Crater's exchange-rate fetching historically depended on third-party rate APIs that have since moved to keyed/paywalled tiers. If multi-currency totals look wrong or stale, check the exchange-rate service config and whether rates are being written at all — invoices store the rate at creation time, so bad rates are baked into old records and won't self-correct.

Formatted vs raw amounts. API responses include display-formatted money strings alongside base values. Don't parse "$1,234.56" back into a float — read the numeric fields, and remember currencies with 0 decimals (JPY) and the precision setting will change rounding. Round-tripping through formatted strings is a classic source of off-by-a-cent bugs in payment reconciliation.

One install = one company. There is no built-in multi-tenancy. Running several businesses means several databases/instances (acceptable, but plan the backup and upgrade story) or a genuine fork (expensive). Decide before you build.

Migrations are a one-way door. With no maintained upgrade path, a fork that adds columns will diverge from upstream forever. Keep customizations in new tables and new controllers where possible, so you can diff against upstream, and take a DB dump before any pull.

PDF generation is dompdf. Large invoices, non-Latin fonts, and CJK characters are the usual failures — symptoms are blank pages, garbled glyphs, or PHP memory exhaustion. Set memory_limit ≥ 256M for the PDF queue, and verify the font files are in storage/fonts (php artisan vendor:publish for dompdf config if your fork supports it). Test with your worst-case invoice, not a two-line one.

Email deliverability silently fails. If QUEUE_CONNECTION is set but no worker runs, "invoice sent" looks successful in the UI while nothing leaves the server. Verify with php artisan queue:failed and a single Mail::fake-free smoke test to a real inbox before trusting it with customers.

Debugging tips. APP_DEBUG=true plus storage/logs/laravel.log covers most API 500s; 401s are usually the token (check it hasn't been revoked by re-login elsewhere). For 422s, the validation response body lists fields — read it before guessing. php artisan route:list --path=api is the fastest way to confirm which endpoints actually exist in the version you cloned, since community docs lag the code.

Where to extend safely. Observers/model events, new API controllers, new Blade PDF templates, and the resources/scripts Vue layer (for your fork's UI) are all low-friction. Directly editing app/Http/Controllers/API/V1/InvoiceController.php is high-friction — it's the file most likely to conflict if you ever merge upstream.