csgt / utils
CSGT Utils
Maintainers
Requires
- php: >=7.2
Requires (Dev)
- orchestra/testbench: ^8.0|^9.0
- phpunit/phpunit: ^10.5|^11.0
This package is auto-updated.
Last update: 2026-07-31 21:29:33 UTC
README
Internal Softlogic package that scaffolds and standardizes CSGT Laravel projects. It publishes the CI/CD pipeline (make:csgtci), the Docker environment (make:csgtdocker), the standard documentation (make:csgtdocs) and the base app scaffolding (make:csgtutils), and ships the shared admin utilities used by every project (users/roles/profile controllers, menu rendering and misc helpers).
Versions
One branch per major version — every version is in active use by projects pinned to it, so fixes are applied to the branch of the affected version. Install the line that matches your project:
composer require csgt/utils:^10.0
| Package Version | Laravel UI | Cancerbero | Crud version | Menu Table | AdminLTE | Vue | PHP | Webserver |
|---|---|---|---|---|---|---|---|---|
| 5.0 | no | names | ? | es | ? | 2 | ? | nginx |
| 6.0 | no | names | ? | en | ? | 2 | ? | nginx |
| 5.7 | no | names | ? | en | ? | 2 | ? | nginx |
| 7.0 | yes | names | ? | en | ? | 2 | ? | nginx |
| 8.0 | yes | names | 7 | en | 3.2.0-beta | 2 | ? | nginx |
| 9.0 | yes | names | 8 | en | 4.0.0-alpha | 3 | 8.1 | octane |
| 10.0 | yes | names | 8 | en | 4.0.0-alpha | 3 | 8.2 | octane |
Menu
To render the menu, use the following snippet. This will auto-generate the required structure needed for the csgt/menu package.
{!! \Csgt\Utils\Menu::menu() !!}
CI/CD Pipeline
Publish a GitHub Actions workflow that runs CI (code style, tests, frontend build) on every push and pull request, and deploys to production on the main branch only when CI passes.
php artisan make:csgtci
This creates .github/workflows/ci.yml. Everything is auto-detected so the bare command works without flags: the trigger/deploy branch is the repository's default branch (works for both master legacy and main newer projects), the PHP version is read from composer.json (config.platform.php or require.php), and the Node version from .nvmrc or package.json (engines.node). Pass flags only to override the detection:
php artisan make:csgtci --php=8.2 --node=18 --branch=master
| Option | Default | Description |
|---|---|---|
--php |
auto-detected (composer.json) |
PHP version used by the CI job |
--node |
auto-detected (.nvmrc/package.json) |
Node version used by the CI job |
--branch |
auto-detected | Branch that triggers CI and deployment |
--force |
— | Overwrite the workflow if it already exists |
The ci job is universal and rarely needs editing. Projects without tests pass CI harmlessly: the test step skips when no phpunit.xml is present and becomes enforcing once tests exist.
The deploy job is project-specific (host, Docker, Octane, etc.). Configure the repository secrets:
| Secret | Required | Description |
|---|---|---|
PRODUCTION_HOST |
yes | Server hostname or IP |
PRODUCTION_USER |
yes | SSH user |
PRODUCTION_PATH |
yes | Absolute path of the project on the server |
PRODUCTION_SSH_KEY |
yes | Unencrypted private deploy key (no passphrase) |
PRODUCTION_SSH_PORT |
no | SSH port (defaults to 22) |
PRODUCTION_SSH_KNOWN_HOSTS |
no | Pinned host key; prevents MITM (falls back to keyscan) |
PRODUCTION_HEALTHCHECK_URL |
no | URL checked after deploy; deploy fails if not HTTP 200 |
CI runs are cancelled when superseded by a newer commit, but deployments are never cancelled mid-flight (concurrent pushes queue) to avoid leaving the server half-migrated.
After migrating, the deploy runs db:seed --force and then db:seed --class=GodSeeder --force (the latter only when database/seeders/GodSeeder.php exists). The ACL — modules, permissions and menu — is generated from the seeders, so without this step new permissions never reach production even though the migrations do. This is safe to repeat because CSGT seeders rebuild derived data (clear then insert, or updateOrInsert). If a project adds a seeder with business data, guard it or keep it out of DatabaseSeeder, otherwise it re-runs on every deploy.
Docker environment
Publish the local Docker environment (Ubuntu 24.04 + Octane/Swoole on port 81, MySQL and Redis):
php artisan make:csgtdocker
This creates the following files, with no options to configure:
docker-compose.ymlanddocker-compose.yml.example—app,mysqlandredisservices.apppublishes127.0.0.1:80(Octane) and127.0.0.1:5173(Vite), mounts the project at/var/www, and waits for MySQL to start and Redis to pass its healthcheck. MySQL data persists in themysql-datavolume.dockerfiles/app/Dockerfile— the app image (PHP with Swoole, Node, Composer). Build args:NODE_VERSION(defaults to 24) andSUPERVISOR_OCTANE_EXTRA(set to--watchin the compose file so Octane reloads on file changes).dockerfiles/app/php.ini,supervisord.conf,start-container,scheduler.sh— container runtime config. Supervisor runs Octane; thehorizonandschedulerprograms ship commented out, enable them per project.dockerfiles/mysql/Dockerfile— the MySQL image.
The command aborts if a dockerfiles/ directory already exists (there is no --force); remove it first to regenerate. Unlike the CI/CD workflow, these files are usually tuned per project after publishing.
Documentation
Publish the standard project documentation:
php artisan make:csgtdocs
This creates three files from company-wide templates:
README.md— stack, local setup, frequent commands, CI/CD summary, plus clearly markedEDIT/TODOsections for the project's business domain.AGENTS.md— guidance for AI coding agents (the cross-tool standard read by Codex, Gemini CLI, Cursor, etc.): stack, CSGT conventions (commits, migrations, cancerbero, CRUD pattern, testing checklist, generated files), environment commands, plus editable project-context sections.CLAUDE.md— a two-line pointer that importsAGENTS.mdfor Claude Code, so the guidance lives in a single tool-agnostic file.
Project name, repository (for the CI badge), PHP and Node versions are auto-detected (composer.json, git remote, .nvmrc). Existing files are never overwritten unless --force is passed. After generating, search for the EDIT/TODO markers and fill in the project-specific sections.
| Option | Default | Description |
|---|---|---|
--php |
auto-detected (composer.json) |
PHP version shown in the docs |
--node |
auto-detected (.nvmrc/package.json) |
Node version shown in the docs |
--force |
— | Overwrite README.md/CLAUDE.md if present |
Base scaffolding
Publish the base app structure expected by the package's admin utilities:
php artisan make:csgtutils
This creates the app/Http/Controllers/Catalogs and app/Models/Menu directories, and writes app/Models/Menu/Menu.php (an empty Eloquent model, namespaced to the app) that backs the Menu rendering below. Existing files are overwritten, so run it once when setting up a project rather than on an established codebase.
Package development
Work targets the branch of the affected version (master is the current major). The test suite runs the scaffolding commands against a real Laravel skeleton via orchestra/testbench:
composer install
composer test
Every push runs the suite on GitHub Actions across this branch's PHP matrix (.github/workflows/tests.yml). Releases are tags: a fix on a version branch ships by tagging the next patch on that branch (Composer installs tags, not branches).