Getting Started

This is a Symfony 2 bundle targeting Symfony 2.8 LTS. The latest release, v1.0.4 (2018-02-22), is a compatibility bump whose only stated change is "Upgrade to symfony 2.8" — no new features, no API changes. Before anything else, decide whether you're maintaining a legacy Symfony 2.8 application or trying to port it forward. The bundle will not install cleanly on Symfony 3.4+/4+/5+, and Composer will fight you on transitive deps (symfony/symfony, Doctrine, KnpSnappy, etc.). If you're on Symfony 2.8, proceed; otherwise plan to fork and modernize the constraints, not require it fresh.

Minimal bring-up on Symfony 2.8:

Require with a pinned version. Use ^1.0.4 — that's the release that declares Symfony 2.8 support. If you're pinned to an older 1.0.x you're on a build with looser/older Symfony constraints. Install with --ignore-platform-reqs if your local PHP is newer than 7.0/7.1 (the era this targets).
```
"sgl/flts-bundle": "^1.0.4"
```
Register the bundle in app/AppKernel.php:
```
new SGL\FLTSBundle\SGLFLTSBundle(),
```
Confirm the exact namespace from the bundle's DependencyInjection extension — historically SGL\FLTSBundle but casing matters on case-sensitive filesystems.

Import routing in app/config/routing.yml:

sgl_flts:
    resource: "@SGLFLTSBundle/Resources/config/routing.yml"
    prefix:   /flts

Create the schema. This is the step that trips people up — there are no shipped migrations, so use the bundle's Doctrine entities directly:
```
php app/console doctrine:schema:update --dump-sql   # review first
php app/console doctrine:schema:update --force
```
First use case: log in as an admin (the bundle ships its own security config in Resources/config/ — check security.yml there and merge, don't blindly copy over your existing one), create a Client, then a Project under that client, then start a Timesheet against the project. That Client → Project → Timesheet → Invoice chain is the core workflow and where you'll spend most of your day.

Where to look first in the repo:

Entity/ — the domain model is the source of truth. Read these before touching config.
Controller/ — understand what's already exposed vs. what you'll need to add.
Resources/config/services.xml / routing.yml — anything surprising (custom services, admin prefixes) is here.
Resources/views/ — Twig templates are the fastest way to understand the intended UX.

Implementation Patterns

Treat it as a bounded context, not a full app. The bundle gives you entities and CRUD controllers for freelancer billing; it does not give you a polished product. In practice you'll embed it inside an existing Symfony app (which almost certainly has its own User entity) and adapt the security configuration — the bundle's User reference needs mapping to yours.

Version strategy: stay on ^1.0.4. There's no reason to be on 1.0.3 or earlier — 1.0.4 is where the Symfony 2.8 constraint lands. If you maintain a fork, rebase on 1.0.4 rather than merging forward from 1.0.x, since the diff is mostly composer.json constraint churn.

Typical daily workflow:

Timesheet entry is the highest-frequency operation. If you're building a custom dashboard, call the timesheet repository directly rather than driving the bundle's form controllers from AJAX. Most forks end up wrapping the bundle's services in a thin application layer.
Invoice generation is a batch operation, not a web request. Schedule it via app/console (a custom Command that instantiates the invoice service and iterates unbilled timesheet entries for a client/period). The bundle's controller-based invoice creation is fine for one-off manual invoices but is not what you want for monthly billing runs.
PDF output (if the bundle uses KnpSnappy / wkhtmltopdf) is fragile in containerized environments. Pin the wkhtmltopdf binary version in your Docker image, and generate PDFs in a queue/worker rather than inline in the request.

Integration tips:

Override templates via app/Resources/SGLFLTSBundle/views/ rather than editing vendor code. Symfony 2's bundle override convention still works and is the only sane way to make the UI match your app.
Extend entities with a mapped superclass. If you need to add fields (e.g., vatRate, currency) to Client or Invoice, use Doctrine @MappedSuperclass inheritance or an association-table sidecar — do not patch the vendor entities. Sidecar tables survive composer update; patched entities do not.
Isolate in a sub-application if possible. If your main app runs Symfony 3.4+, run FLTS on a separate 2.8 host with shared auth (SSO cookie or OAuth) rather than fighting the dependency graph in one kernel.
Wrap the money math. The bundle predates moneyphp/money adoption. Store amounts in the bundle's schema as-is (likely integer cents or DECIMAL — verify in Entity/), and do all arithmetic in your own value objects, converting at the boundary.

Where it shines: if you've got an existing Symfony 2.8 freelancer-facing app and need a timesheet/invoice module today, this saves you a week of schema and CRUD scaffolding. Read the entities, override the templates, write your own batch commands.

Gotchas and Tips

v1.0.4 is a constraint release, not a fix release. It raises the Symfony floor to 2.8. Two consequences: (a) you cannot run it on Symfony 2.0–2.7 — stay on older 1.0.x there, which is a dead end; (b) "upgrade to 2.8" releases frequently touch only composer.json and leave code paths written against 2.7-era behavior untouched. After bumping, smoke-test the full Client → Project → Timesheet → Invoice chain plus your batch invoice command before deploying; don't assume a green composer update means the app works.
The dependency graph is the real problem. Last release 2018-02-22, effectively abandoned, no meaningful dependent base — assume no upstream fixes. Before composer require, run composer why-not sgl/flts-bundle after adding it to see what conflicts. Budget for a fork the first time you need a security patch.
No migrations. You get raw entities and doctrine:schema:update. Snapshot the SQL once and commit it as a baseline migration; otherwise every schema-touching change in your app risks blowing away FLTS tables in prod.
Security config collision. The bundle ships its own security.yml fragment. Merging it with an app that already has firewalls will produce silent firewall ordering bugs — the user ends up authed against the wrong provider. Diff both files line-by-line; don't copy.
Date/timezone handling. Timesheet entries are timestamped; the bundle likely reads date_default_timezone_set from the kernel. Set php.intl and the timezone in php.ini/config.yml explicitly — silently mismatched timezones will produce invoices that span the wrong billing period.
Currency and rounding. Verify whether amounts are stored as floats, DECIMAL, or cents. If floats, round at the line-item level and re-sum, not at the total. Freelancer tax authorities care about this.
Templates are bare. Expect unstyled Bootstrap 2/3-era Twig. Plan an afternoon to restyle, or strip them and use your app's layout.
Debugging a stuck form: the bundle's controllers predate Symfony's FormEvents conventions in places. If a form silently discards fields, check for PRE_BIND/BIND (Symfony 2.0-era) event usage that should be PRE_SUBMIT. Note that 1.0.4 would not have migrated these — verify against the source.
Extension points are limited. The best escape hatches are (a) template override, (b) Doctrine event subscribers on the bundle's entities to inject your own behavior, and (c) a thin application service that wraps the bundle's repositories. There's no formal plugin system — don't look for one.
Don't expose the admin routes publicly. The bundle assumes an authenticated admin and does not ship CSRF-aware guards on every custom action. Verify each POST route under Controller/ before going live.
For anything new, prefer a modern replacement. If the goal is greenfield, solidinvoice, invoiceplane, or a small custom Laravel/Symfony 6 module will serve you far better than fighting this bundle's PHP 5.6-era code. Fork this only when the Symfony 2.8 sunk cost is real.

Flts Bundle Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips