Download the PHP package dcardenasl/ci4-api-scaffolding without Composer

ci4-api-scaffolding

CRUD scaffolding engine for CodeIgniter 4 APIs built on dcardenasl/ci4-api-core. One command generates DTOs, service, controller, migration, routes, language files, and tests — all wired to the ci4-api-core base classes.

Pre-1.0 policy: MINOR bumps may contain breaking changes. Pin to ~0.x.0 or exact version until v1.0.0.

Table of Contents

• Requirements
• Installation
• Quick Start
• Configuration
• Available Commands
• Field Types
• Field Modifiers
• Generated Artifacts
• Scaffolding Boundaries
• Compatibility Matrix
• Development
• Troubleshooting
• Example Project

Requirements

• PHP ^8.2
• CodeIgniter 4 ^4.7
• dcardenasl/ci4-api-core ^0.9 (installed automatically as a dependency)

Installation

Quick Start

Configuration

Create app/Config/Scaffolding.php extending BaseScaffoldingConfig. If your project follows ci4-api-starter conventions, the bundled defaults work without any overrides:

To customize base classes, paths, or route filters, pass named arguments to ScaffoldingConfig:

Default route filters (when no Scaffolding config is found): ['jwtauth', 'permission:iam.superadmin-access', 'throttle']. New resources are unreachable by non-superadmins until you intentionally loosen this filter.

All configurable options (ScaffoldingConfig constructor parameters):

Path overrides (ScaffoldingPaths constructor parameters, all relative to APPPATH):

Available Commands

Always use vendor/bin/make-crud.sh in non-TTY environments (CI, Claude Code, scripts). php spark make:crud falls back to interactive mode when --fields is not provided, which hangs in non-TTY contexts.

make:crud — full options

make:crud:remove — full options

--force skips the confirmation prompt (useful in CI). Without --force, the command lists the files it would delete and asks for confirmation.

module:check / validate-crud.sh

Validates 14 post-scaffold wiring checkpoints: migration exists, table naming, soft-delete consistency, controller/model/service/route presence, Services.php wiring, language files, test files. Exits non-zero if any checkpoint fails.

scaffold:check

Read-only diagnostic — never writes files. Verifies that app/Config/Scaffolding.php exists, extends BaseScaffoldingConfig, and that all 14 FQCNs it declares (base classes, interfaces, traits) are loadable. Run after first install or after bumping dcardenasl/ci4-api-core to confirm the config still points at real classes.

If the file is missing, the command prints the cp command to bootstrap a default config from the bundled example.

swagger:generate

Generates public/swagger.json from OpenAPI annotations. Scans app/Config/OpenApi.php, app/Controllers/, app/Documentation/, app/DTO/, and vendor/dcardenasl/ci4-api-core/src/Dto/ by default. Requires zircote/swagger-php in the consumer's require-dev:

To scan additional directories, subclass the command and override scanPaths():

Field Types

Field type codes used in the --fields string. All types are recognized case-sensitively.

FK field syntax — uses a 4-segment form because the target table name is a required third segment:

Field Modifiers

Modifiers follow the type (or the FK table) and are separated by |:

Full example:

Boolean validation contract — bool currently maps to boolean_like, which is part of the supported starter contract (ci4-api-starter and ci4-domain-starter both ship and register that custom rule). If a non-starter consumer uses this package, it must expose an equivalent boolean_like validation rule or adapt the generated rule set after scaffolding.

Generated Artifacts

make:crud Article Blog 'title:string:required' yes creates 17 files:

Services.php is also updated (or a snippet is printed with --no-wire) to register the new service and response mapper.

Scaffolding Boundaries

make:crud is designed for flat CRUD resources. It gives you a correct starting module for entities that behave like:

• one primary table
• standard list/show/create/update/delete
• scalar fields and conventional foreign keys
• standard DTO/model/controller/service wiring

It is not a full aggregate generator. If your resource needs any of the following, expect manual extension after scaffolding:

• custom workflow actions such as publish, archive, approve
• nested sub-resources such as /items/{id}/media
• relation arrays in payloads such as tag_ids[] or embedded media[]
• pivot tables with composite primary keys and no synthetic id
• cross-field invariants such as "if is_for_sale=true, then price and currency are required"
• response enrichment that joins child collections or computed data

Practical rule:

• use make:crud to establish the module skeleton and conventions
• then evolve the generated service/controller/routes into an aggregate by hand

The scaffolder is successful when it removes boilerplate and preserves architectural consistency. It is not trying to replace domain modeling for complex aggregates.

CSV export/import is intentionally outside the upstream API scaffold contract. In this workspace, that admin-facing bulk workflow lives in ci4-admin-starter, where the generator can align the export route with the current index filters and surface import validation in the admin UI.

Compatibility Matrix

* PHP 8.4 is tested against the locked CI4 version in the test job. The explicit CI4-compatibility matrix covers PHP 8.2 and 8.3. CI4 4.5.x and 4.6.x were dropped: 4.5.x for security advisories, 4.6.x because v0.3.2 widened the floor to ^4.7.

CI runs on every push: PHPStan level 8, PHP CS Fixer, full unit suite, E2E smoke test (creates a real CI4 project and scaffolds into it). PHP 8.2 additionally collects coverage.

Development

For architecture constraints that generated code must satisfy, see docs/ARCHITECTURE_CONTRACT.md.

Troubleshooting

--fields is empty / scaffold produces a partial module Always single-quote the fields string. Unquoted pipes (|) are consumed by the shell before the command sees them:

php spark make:crud hangs in a script / CI It entered interactive mode because --fields was empty and stdin is not a TTY. Use vendor/bin/make-crud.sh instead, which guards against this and requires --fields in non-TTY contexts.

Wiring failed / Services.php was not modified The ConfigWireman uses AST-based injection and expects Services.php to follow the CI4 convention (a class with static factory methods in a trait). Run with --no-wire to get the snippet to paste manually:

FK validation aborts because the DB is unreachable Pass --skip-fk-validation when you know the target tables exist but the DB isn't available (e.g. in a fresh setup before migrate):

Scaffolded routes don't appear in php spark routes:list New route files are not hot-reloaded. Restart the server after scaffolding:

module:check fails on a valid module Run php spark module:check <Resource> --domain <Domain> to see which of the 14 checkpoints failed and why.

Example Project

ci4-api-core-example is a complete, runnable Catalog API (Categories + Products) built entirely with this scaffolding engine — minimal hand-written code. Each step is a separate git commit so you can trace exactly what make-crud.sh generates, from a blank CI4 project to a production-ready API with filtering, searching, pagination, and OpenAPI docs.

License

MIT — see LICENSE.