README

A Laravel code generator that turns JSON entity definitions into a working application or a reusable Composer package. Magic wires migrations, models, controllers, Vue/Inertia pages, tests, and boilerplate Laravel setup so you can prototype or bootstrap production features in minutes.

Table of contents

1. What Magic does
2. Requirements
3. Installation
4. Running the generator
5. Understanding configuration
6. Package mode
7. File generation reference
8. Resetting a build
9. Customising stubs & namespaces
10. Testing and quality tools
11. Troubleshooting
12. Contributing
13. License

What Magic does

Magic reads a JSON schema that describes your domain (entities, relations, presets, UI metadata) and executes a predictable build pipeline:

1. Resolve configuration and normalise paths.
2. Publish starter assets and language files.
3. Install the required Composer and NPM dependencies (host builds only).
4. Generate migrations, models, enums, factories, seeders, REST controllers, form requests, API resources, TypeScript definitions, Vue pages, and Pest tests.
5. Register routes, Sanctum middleware, queues, and Inertia bootstrapping when targeting a Laravel application.
6. Produce a manifest of generated files so resets can be executed safely.

Every build step is implemented as a dedicated action under src/Actions/Build, making the pipeline easy to extend or re-order for your own needs.

Requirements

Tip: Magic ships as a regular Laravel package. You can install it globally in a host Laravel app or use package mode to generate a standalone Composer package that you pull into multiple projects.

Installation

Install into a Laravel application

1. Create or open a Laravel application that already has Breeze/Inertia (Vue) installed.
2. Require Magic as a dev dependency:

   composer require glugox/magic --dev

3. Publish the configuration file:

   php artisan vendor:publish --provider="Glugox\\Magic\\MagicServiceProvider"

4. Optional: explore the sample configurations in stubs/samples.

Install for package generation

If you plan to generate re-usable features as a package, install Magic in a throwaway Laravel project and run the generator with the package flags (described below). Magic will emit a new Composer package that you can require in your real application.

Running the generator

Magic exposes one primary Artisan command:

php artisan magic:build [options]

Examples:

# Generate directly into the Laravel application
php artisan magic:build --starter=inventory

# Generate a package under ./packages/inventory-kit
php artisan magic:build \
  --config=stubs/samples/inventory.json \
  --package-path=packages/inventory-kit \
  --package-namespace=Acme\\Inventory \
  --package-name=acme/inventory-kit

Magic prevents accidental overwrites by checking for storage/magic/generated_files.json. Run php artisan magic:reset (see below) before triggering a new build in the same environment.

Understanding configuration

• Configuration files follow json-schema.json and can be validated automatically by most editors.
• Each config declares global app metadata (name, base namespace overrides, Faker mappings, seeding flags) and an array of entities.
• Entities describe fields, relations, filters, table presets, navigation icons, and test scenarios.
• Sample configs live in stubs/samples; the inventory.json example demonstrates most features.

A minimal entity definition:

{
  "app": {
    "name": "Inventory",
    "seedEnabled": true
  },
  "entities": [
    {
      "name": "Product",
      "icon": "Package",
      "fields": [
        { "name": "name", "type": "string", "rules": ["required"] },
        { "name": "sku", "type": "string", "unique": true },
        { "name": "price", "type": "decimal", "precision": 12, "scale": 2 }
      ],
      "relations": [
        { "type": "belongsTo", "name": "category", "entity": "Category" }
      ]
    }
  ]
}

When a build runs, the configuration is parsed into strongly typed objects (src/Support/Config) so generators can reason about default values and relationships safely.

Package mode

Package mode rewires Magic so that every generated file lands inside a Composer package instead of your Laravel app. Three options must be provided: --package-path, --package-namespace, and --package-name.

Key behaviours:

• MagicPaths swaps Laravel helpers (app_path, database_path, etc.) for equivalents rooted inside the target package directory.
• MagicNamespaces ensures PHP namespaces resolve under your chosen base namespace (controllers, models, resources, providers, and tests are all updated).
• InitializePackageAction prepares the destination by creating a Laravel-like directory tree, generating a Composer manifest with PSR-4 autoloading, and scaffolding a MagicPackageServiceProvider that registers routes, views, migrations, and translations when installed into a host app.
• Host-only steps—environment tweaks, dependency installation, queue setup, Sanctum middleware mutations, and Vue bootstrapping—are skipped so the package remains framework-agnostic.
• Seeders generated inside a package avoid touching DatabaseSeeder.php; consumers can opt-in by calling the package service provider’s seeders manually.

After running the generator in package mode:

1. Commit the generated package to its own repository (or keep it inside a monorepo under packages/).
2. Require it from your real Laravel application via VCS or path repositories.
3. Register the generated service provider if you disable Laravel’s automatic package discovery.

Example of generating a package called glugox/module-a with the orchestrator starter:

php artisan magic:build --package-path ./modules/glugox/module-a --package-name glugox/module-a --package-namespace Glugox\\ModuleA --starter orchestrator

File generation reference

Refer to the corresponding action classes in src/Actions/Build for implementation details.

Resetting a build

Use the reset command when you need to revert the generated artefacts inside a Laravel application:

php artisan magic:reset --starter=inventory

magic:reset replays the manifest from storage/magic/generated_files.json, deletes migrations, models, seeders, controllers, Vue pages, TypeScript artefacts, and restores modified Laravel files to their original state before optionally refreshing the database. Package builds can be reset manually by deleting the destination directory and re-running magic:build.

Customising stubs & namespaces

• All PHP and Vue stubs live under stubs/; copy them into your application and update config/magic.php if you need to override defaults.
• MagicNamespaces lets you change the base namespace for generated classes. Provide the --package-namespace option or edit the configuration’s app.namespace value when targeting a Laravel app.
• MagicPaths centralises every filesystem lookup so package builds, tests, and workbench usage stay isolated. Clearing paths/namespaces after each command prevents leakage into subsequent Artisan calls.

Testing and quality tools

The project uses Pest, PHPStan, Laravel Pint, and Rector. Run everything locally with:

composer install
composer test      # pest + pint --test
composer analyse   # phpstan
composer format    # pint (fixes)

When contributing, make sure your feature and unit tests cover new behaviour—especially when altering generators or stubs.

Troubleshooting

• Manifest file exist error – run php artisan magic:reset before starting a new build in the same Laravel project.
• Missing Vue components in package builds – Magic scaffolds Vue files from built-in stubs when resources/js/components/AppSidebar.vue or AppLogo.vue is absent.
• Routes not registered after installing a package – confirm that the generated MagicPackageServiceProvider is discovered (Composer autoload dump + Laravel package discovery) and that routes/app.php and routes/app/api.php exist in your package.
• Need to skip seeding in a package – by design Magic avoids touching DatabaseSeeder.php during package builds; call package seeders manually from the consuming app if required.

Contributing

Issues and pull requests are welcome! If you are planning a large change, please open an issue first so we can discuss scope and direction. When submitting a PR:

1. Add or update tests.
2. Run the QA commands listed above.
3. Document user-facing changes in this README or the changelog.

You can also reach out directly at ervinbeciragic@gmail.com.

License

Magic is open-sourced software licensed under the MIT license.