Fatfree

A powerful yet easy-to-use PHP micro-framework designed to help you build dynamic and robust Web applications - fast!

Condensed in a single file, F3 (as we fondly call it) gives you solid foundation, a mature code base, and a no-nonsense approach to writing Web applications. Under the hood is an easy-to-use Web development tool kit, a high-performance URL routing and cache engine, built-in code highlighting, and support for multilingual applications. It's lightweight, easy-to-use, and fast. Most of all, it doesn't get in your way.

Whether you're a novice or an expert PHP programmer, F3 will get you up and running in no time. No unnecessary and painstaking installation procedures. No complex configuration required. No convoluted directory structures. There's no better time to start developing Web applications the easy way than right now!

F3 supports both SQL and NoSQL databases off-the-shelf: MySQL, SQLite, MSSQL/Sybase, PostgreSQL, DB2, and MongoDB. It also comes with powerful object-relational mappers for data abstraction and modeling that are just as lightweight as the framework. No configuration needed.

That's not all. F3 is packaged with other optional plug-ins that extend its capabilities:-

• Fast and clean template engine,
• Unit testing toolkit,
• Database-managed sessions with automatic CSRF protection,
• Markdown-to-HTML converter,
• Atom/RSS feed reader,
• Image processor,
• Geodata handler,
• Google static maps,
• On-the-fly Javascript/CSS compressor,
• OpenID (consumer),
• Custom logger,
• Basket/Shopping cart,
• Pingback server/consumer,
• Unicode-aware string functions,
• SMTP over SSL/TLS,
• Tools for communicating with other servers,
• And more in a tiny supercharged package!

Unlike other frameworks, F3 aims to be usable - not usual.

The philosophy behind the framework and its approach to software architecture is towards minimalism in structural components, avoiding application complexity and striking a balance between code elegance, application performance and programmer productivity.

Table of Contents

• Getting Started
• Routing Engine
• Framework Variables
• Views and Templates
• Databases
• Plug-Ins
• Optimization
• Unit Testing
• Quick Reference
• Support and Licensing

Get the latest release!

F3 has a stable enterprise-class architecture. Unbeatable performance, user-friendly features and a lightweight footprint. What more can you ask for? To get this package, simply download this package or visit the fatfree-core repository to find the latest edge-version.

For all composer users out there:

• start a new project using composer create-project bcosca/fatfree
• add fatfree to your existing project with composer require bcosca/fatfree-core

It is highly recommended that experienced users develop new applications with the latest version to take advantage of an updated code base and ongoing improvements.

Please visit FatFreeFramework.com

The most up-to-date user-guide and detailed API documentation with lots of code examples and a graphic guide can be found at fatfreeframework.com/.

Of course this handy online reference is powered by F3! It showcases the framework's capability and performance. Check it out now. If you'd like to read it at github directly, you can find the websites content at github.com/F3Community/F3com-data

Getting Started

A designer knows he has achieved perfection not when there is nothing left to add, but when there is nothing left to take away. -- Antoine de Saint-Exupéry

Fat-Free Framework makes it easy to build entire Web sites in a jiffy. With the same power and brevity as modern Javascript toolkits and libraries, F3 helps you write better-looking and more reliable PHP programs. One glance at your PHP source code and anyone will find it easy to understand, how much you can accomplish in so few lines of code, and how powerful the results are.

F3 is one of the best documented frameworks around. Learning it costs next to nothing. No strict set of difficult-to-navigate directory structures and obtrusive programming steps. No truck load of configuration options just to display 'Hello, World' in your browser. Fat-Free gives you a lot of freedom - and style - to get more work done with ease and in less time.

F3's declarative approach to programming makes it easy for novices and experts alike to understand PHP code. If you're familiar with the programming language Ruby, you'll notice the resemblance between Fat-Free and Sinatra micro-framework because they both employ a simple Domain-Specific Language for ReSTful Web services. But unlike Sinatra and its PHP incarnations (Fitzgerald, Limonade, Glue - to name a few), Fat-Free goes beyond just handling routes and requests. Views can be in any form, such as plain text, HTML, XML or an e-mail message. The framework comes with a fast and easy-to-use template engine. F3 also works seamlessly with other template engines, including Twig, Smarty, and PHP itself. Models communicate with F3's data mappers and the SQL helper for more complex interactions with various database engines. Other plug-ins extend the base functionality even more. It's a total Web development framework - with a lot of muscle!

Enough Said - See For Yourself

Unzip the contents of the distribution package anywhere in your hard drive. By default, the framework file and optional plug-ins are located in the lib/ path. Organize your directory structures any way you want. You may move the default folders to a path that's not Web-accessible for better security. Delete the plug-ins that you don't need. You can always restore them later and F3 will detect their presence automatically.

Important: If your application uses APC, Memcached, WinCache, XCache, or a filesystem cache, clear all cache entries first before overwriting an older version of the framework with a new one.

Make sure you're running the right version of PHP. F3 does not support versions earlier than PHP 7.2. You'll be getting syntax errors (false positives) all over the place because new language constructs and closures/anonymous functions are not supported by outdated PHP versions. To find out, open your console (bash shell on GNU/Linux, or cmd.exe on Windows):-

/path/to/php -v

PHP will let you know which particular version you're running and you should get something that looks similar to this:-

PHP 8.3.11 (cli) (built: Aug 30 2024 20:21:32) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.3.11, Copyright (c) Zend Technologies
    with Xdebug v3.3.2, Copyright (c) 2002-2024, by Derick Rethans

Upgrade if necessary and come back here if you've made the jump to PHP 8.0 or a later release. Fat-Free needs at least PHP 7.2 as minimum version to function.

Hello, World: The Less-Than-A-Minute Fat-Free Recipe

Time to start writing our first application:-

$f3 = require('path/to/base.php');
$f3->route('GET /',
    function() {
        echo 'Hello, world!';
    }
);
$f3->run();

Prepend base.php on the first line with the appropriate path. Save the above code fragment as index.php in your Web root folder. We've written our first Web page.

Using composer? Then just run composer require bcosca/fatfree-core and use the following:

require 'vendor/autoload.php';
$f3 = \Base::instance();
$f3->route('GET /',
    function() {
        echo 'Hello, world!';
    }
);
$f3->run();

The first command tells the PHP interpreter that you want the framework's functions and features available to your application. The $f3->route() method informs Fat-Free that a Web page is available at the relative URL indicated by the slash (/). Anyone visiting your site located at http://www.example.com/ will see the 'Hello, world!' message because the URL / is equivalent to the root page. To create a route that branches out from the root page, like http://www.example.com/inside/, you can define another route with a simple GET /inside string.

The route described above tells the framework to render the page only when it receives a URL request using the HTTP GET method. More complex Web sites containing forms use other HTTP methods like POST, and you can also implement that as part of a $f3->route() specification.

If the framework sees an incoming request for your Web page located at the root URL /, it will automatically route the request to the callback function, which contains the code necessary to process the request and render the appropriate HTML stuff. In this example, we just send the string 'Hello, world!' to the user's Web browser.

So we've established our first route. But that won't do much, except to let F3 know that there's a process that will handle it and there's some text to display on the user's Web browser. If you have a lot more pages on your site, you need to set up different routes for each group. For now, let's keep it simple. To instruct the framework to start waiting for requests, we issue the $f3->run() command.

Can't Get the Example Running? If you're having trouble getting this simple program to run on your server, you may have to tweak your Web server settings a bit. Take a look at the sample Apache configuration in the following section (along with the Nginx and Lighttpd equivalents).

Still having trouble? Make sure the $f3 = require('path/to/base.php'); assignment comes before any output in your script. base.php modifies the HTTP headers, so any character that is output to the browser before this assignment will cause errors.

Routing Engine

Overview

Our first exa