bcosca/fatfree: the PHP micro-framework that ships as one file

What Fat-Free Framework is for, and who it is for

F3 targets PHP developers who want routing, templates, database access and caching without adopting a directory convention. The README frames the design goal as minimalism in structural components, and the practical consequence is that you organize files however you like. Nothing in the repository forces a src/ or app/ tree; the top level holds index.php, config.ini, composer.json and a lib/ directory, and the README states you may move the default folders to a path that is not Web-accessible.

The intended audience is broad by design. The README says both novices and experts can get running in no time, and it repeatedly contrasts F3 with frameworks that require configuration before printing a greeting. That is a real positioning choice rather than a slogan: the framework file and the optional plug-ins live in lib/, and the README says F3 detects plug-in presence automatically. If you have written a small PHP service and resented the scaffolding, this is the pitch you are being sold.

How the routing, template and data mapper layers fit together

The framework is condensed into a single file, and the README describes what sits under that surface: URL routing, a cache engine, code highlighting, multilingual support, a template engine, and object-relational mappers for SQL and NoSQL databases. The topics list on the repository names the same pieces individually: cache-engine, database-engine, datamapper, html-template, route-handler, sql-engine, sql-mapper, template-engine.

The data flow the README sketches is conventional for a micro-framework. A route handler receives the request, a view renders the response, and models talk to the data mappers and the SQL helper for anything more complex than a simple query. Views are not restricted to HTML: the README says they can be plain text, HTML, XML or an email message, and that F3 works with Twig, Smarty and plain PHP as well as its own template engine.

Database support is listed off the shelf for MySQL, SQLite, MSSQL/Sybase, PostgreSQL, DB2 and MongoDB, with the README claiming no configuration is needed. Treat that claim carefully. Connection credentials still have to live somewhere, and the repository ships a config.ini at the top level, which is the obvious place for them. The interesting part is the mapper layer: it lets you model records as objects rather than hand-writing queries, which is the feature that separates F3 from a bare router.

Installing bcosca/fatfree and rendering a first route

The README gives two Composer paths. To start a fresh project, run the create-project command. To add the framework to an existing codebase, require the core package instead. Note that the second package name differs from the repository name, and that is exactly how the README writes it.

composer create-project bcosca/fatfree
# or, inside an existing project:
composer require bcosca/fatfree-core

Before any of that, confirm your interpreter. The README is explicit that F3 does not support PHP versions earlier than 7.2, and warns that older versions produce syntax errors that look like false positives because closures and newer language constructs are unsupported. The command it gives is a plain version check.

/path/to/php -v

The README shows the kind of output you should see, a version banner followed by the Zend Engine line, with the example built on PHP 8.3.11. If your banner reads 7.1 or lower, stop there.

The other installation route is manual. The README says to unzip the distribution anywhere on disk, that the framework file and optional plug-ins land in lib/ by default, and that you may delete plug-ins you do not need because F3 restores detection when they return. It also carries a warning worth repeating: if your application uses APC, Memcached, WinCache, XCache or a filesystem cache, clear all cache entries before overwriting an older version with a new one.

The upgrade step the README is loudest about

Most frameworks bury cache invalidation in a migration guide. F3 puts it in the installation section in bold. The README states that if your application uses APC, Memcached, WinCache, XCache or a filesystem cache, you must clear all cache entries before overwriting an older version of the framework with a new one.

That instruction is a direct consequence of the architecture. The cache engine is part of the framework rather than a separate service, and the README lists cache-engine among the repository topics. When the framework file changes underneath a populated cache, stale entries can survive the swap. The README does not document a rollback procedure, so the safe assumption is that recovery means restoring the previous file and clearing the cache again.

There is a second, quieter upgrade hazard. Because plug-ins are detected by presence rather than registered in a manifest, deleting a plug-in from lib/ and later restoring it changes what the framework sees without any configuration edit. That is convenient, and it also means the contents of lib/ are part of your deployment artifact whether or not you think of them that way.

Where Fat-Free Framework is the wrong choice

The single-file design is the selling point and the constraint. Everything the framework does lives in one file, which means the framework is not something you patch in place and expect your changes to survive the next release. If your team's workflow depends on forking internals, F3 fights you.

The README's own language gives away a second boundary. It says F3 aims to be usable, not usual, and that it avoids a strict directory structure. Teams that rely on convention to onboard people quickly will find the freedom expensive: there is no canonical place for models or controllers, so every F3 codebase looks different. A framework that refuses to have opinions transfers those opinions to whoever writes the first file.

Third, the README makes a performance claim in prose without publishing numbers, and the repository's primary language is listed as HTML, which reflects how much of the tree is documentation and UI rather than PHP. Neither fact tells you how the framework behaves under your workload. If you are choosing on throughput, measure it yourself rather than trusting the adjective.

Finally, the README does not document a rollback procedure, and the licence identifier is not stated in the repository metadata available here. The README's support section points to the project website and to the fatfree-core repository for the latest edge version, and the README notes that experienced users are encouraged to develop against the latest version. That is guidance, not a support contract.

Fat-Free Framework compared with Slim and Flight

The related searches around this project are dominated by two names: Slim and Flight. The comparison is worth making concretely, because all three occupy the PHP micro-framework space and they differ in how much they hand you.

Slim is a router and PSR-7/PSR-15 middleware pipeline. Its centre of gravity is HTTP: request and response objects, middleware, and interfaces that other packages plug into. Fat-Free Framework instead bundles its own template engine, its own data mappers, a cache engine, a session handler with CSRF protection, and a long list of optional plug-ins including an image processor, a Markdown converter, an Atom/RSS reader and an SMTP client. If you want to assemble your stack from independent packages, Slim is the shape you want. If you want one file that already contains the stack, F3 is the shape you want.

Flight is closer to F3 in spirit: a small router-first framework with a low ceremony threshold. The difference the README itself draws is with Sinatra and its PHP incarnations, which it says handle routes and requests but stop there. F3's claim is that it goes further, into views, mappers and plug-ins, while keeping the routing layer just as short. Whether that extra surface is a benefit or bloat depends entirely on whether you would have installed those pieces anyway.

Maintenance status, licensing and what to check before adopting

The repository is not archived, and the last push was on 2026-07-21, which is recent relative to the release history: 3.9.3 shipped on 2026-07-21, 3.9.2 on 2025-12-02, and 3.9.1 on 2025-08-09. That cadence is steady rather than rapid, and the README's own advice for experienced users is to develop against the latest version for an updated code base and ongoing improvements.

On licensing, the repository's licence field is unknown, and the README's Support and Licensing section is where the answer lives. The project website is named as the home of the user guide and API documentation. Do not assume a licence from the fact that the source is on GitHub. Read that section before you ship anything, and treat the question as unresolved until you have.

The upgrade cost is low in file count and non-trivial in operational care. You are replacing one framework file and whatever plug-ins you use, and you must clear APC, Memcached, WinCache, XCache or filesystem cache entries first, per the README. There is no documented rollback, so keep the previous framework file until the new one has served traffic.

Editorial conclusion

Adopt bcosca/fatfree if you want routing, templates, data mappers and caching in one file with no configuration ceremony, and you are running PHP 7.2 or newer. Do not adopt it if you want the framework to dictate directory layout, or if you need a documented rollback path: the README does not document one. Verify first that the bundled lib/ plug-ins you intend to use are the ones you actually need, since the README says to delete the ones you do not, and confirm your PHP build with /path/to/php -v before anything else.

Frequently asked questions

Official sources

1. bcosca/fatfree on GitHub
2. Issues
3. README
4. Releases