README

te4g/starter is a one-shot Symfony 8.1 starter kit. It installs a complete account system and a restrained Twig UI directly into a fresh application, validates the result, and then gets out of the way. The generated PHP, configuration, templates, assets, translations, and tests belong to the application; there is no Te4g runtime bundle to deploy.

Requirements

PHP 8.4 or newer
a fresh Symfony 8.1 skeleton or Symfony 8.1 webapp project
Composer 2 with Symfony Flex
an environment where SymfonyCasts TailwindBundle can provide Tailwind CSS 4.3.3 through its normal binary management or an application-configured binary

The installer accepts the security configuration produced by the current Symfony 8.1 skeleton and webapp recipes. It stops when account files already exist or when config/packages/security.yaml has been customized. This is deliberately a fresh-project starter, not an upgrade tool.

Quick start

Run these commands from the root of the new application:

composer require te4g/starter --dev
vendor/bin/te4g-starter install
php bin/console make:migration
php bin/console doctrine:migrations:migrate
composer remove te4g/starter --dev

Review the generated migration before applying it. Installation never opens a database connection, creates a database, generates a migration, or runs a migration. Database work begins only when you run the two explicit Doctrine commands.

The installer promotes the generated application's Composer dependencies, installs its import-map requirements, copies application-owned files, and validates the service container, YAML, Twig, assets, Tailwind build, and offline icons. It generates:

a Doctrine User entity, reset-password request entity, and repositories;
registration and email verification;
password and magic-link login, logout, and login throttling;
password recovery;
profile, email, and password changes;
guarded self-service account deletion;
public, authentication, dashboard, and account layouts built with Twig Components, Turbo, Tailwind CSS, and two focused Stimulus controllers;
functional tests covering the positive workflows and their security boundaries.

There is no dry run, rollback, manifest, or supported rerun. If a subprocess fails, the command exits non-zero and prints the failing phase, exact command, exit code, stdout, and stderr. Preflight and generation conflicts identify the affected path and reason. Files already written before a later validation failure remain application files, so inspect the report and fix or discard the fresh project explicitly.

Production configuration

Set a real Mailer transport before sending account email:

MAILER_DSN=smtp://user:password@mail.example.com:587
APP_URL=https://example.com

Configure Symfony's router so links generated by CLI processes and workers use the public origin:

# config/packages/framework.yaml
framework:
    router:
        default_uri: '%env(APP_URL)%'

Review delivery, queue, retry, and sender policy in the generated App\Mailer\AccountMailer. The starter's validation uses a null transport; production delivery remains the application's responsibility.

Ownership and customization

After generation, edit the files under src/, config/, templates/, assets/, translations/, and tests/ exactly as normal application code. Routes and services use the App\ namespace and the generated code contains no runtime reference to this package. Keep the generated STARTER_LICENSES.md: it scopes the GPL-3.0-only grant for Te4g-authored copied starter resources without assigning a license to independently authored application code, and preserves the MIT/ISC notices for copied UI assets. See customization for the main UI and workflow extension points and security operations before changing authentication behavior.

The companion symfony-template integration plan keeps the template repository thin: it invokes this starter during project creation instead of copying a second account implementation into the template.

Development

To inspect the generated UI in a browser, run:

make preview

The preview target requires the Symfony CLI. It replaces the ignored var/preview/ directory with a fresh Symfony 8.1 web application, installs the development version of the starter from the current checkout, configures an SQLite database and null mail transport, applies the generated migration, and opens http://127.0.0.1:8001 without TLS. Visit /, /login, /register, or /forgot-password; press Ctrl+C to stop the server. Run make preview again after changing generator resources so the disposable application is regenerated from the latest files. To use another port, run PREVIEW_PORT=8010 make preview.

make test does not require a Tailwind binary. The maintainer smoke gate never downloads Tailwind, so provision the pinned Tailwind CSS 4.3.3 binary and pass its absolute path before running it:

export TE4G_TAILWIND_BINARY=/absolute/path/to/tailwindcss
make smoke

make test runs code style, PHPStan, and the complete starter suite with a 512 MB PHPUnit limit. make smoke creates real fresh Symfony 8.1 bare skeleton, Twig-enabled skeleton, and webapp projects, proves installation does not access PostgreSQL, removes te4g/starter, then builds, migrates, boots, and tests each independently owned application. The Twig-enabled skeleton specifically verifies installation before AssetMapper has added its import-map block. make audit audits the locked development dependencies.

The vendored UI provenance and hashes are recorded in resources/shadcn/manifest.json and THIRD_PARTY_NOTICES.md. symfony/ux-toolkit is a development-only dependency used by tools/ShadcnSnapshotSynchronizer.php; it is never required by the generated application at runtime.

te4g / starter

Maintainers

Package info

Statistics

Security