Welcome

RedBeanPHP is a powerful, zero config object relational mapper.
Update 2026: Improved PHP 8.5 compatibility!

Test Server: Online CI/CD has some issues (with latest PHP and oldest PHPs) but don't worry RedBeanPHP is also tested on our local servers and works with PHP 5.2 - PHP 8.5!

News

2026-04-30: RedBeanPHP 5.7.6 Latest
2025-05-30: RedBeanPHP 5.7.5
2024-03-16: Added PHP 8.3 to Travis-CI test matrix
2023-03-18: RedBeanPHP 5.7.4
2022-10-08: RedBeanPHP 5.7.3
2022-04-02: RedBeanPHP 5.7.2
2021-10-31: RedBeanPHP 5.7.1
2021-04-03: RedBeanPHP 5.7
2020-10-04: RedBeanPHP 5.6
2020-04-30: RedBeanPHP 5.5
2019-10-01: RedBeanPHP 5.4
2019-04-06: RedBeanPHP 5.3
2018-11-05: RedBeanPHP 5.2
2017-10-31: RedBeanPHP 5.0

DEMO: Quickly import CSV

Let's import a CSV of country codes in just about a minute, including the time to download and install RedBeanPHP!



With RedBeanPHP you don't need to design your database schema upfront, you don't need a database administrator, you don't need endless configuration files in yaml, xml or json, you don't need hundreds of untrusted dependencies or a sluggish framework, just one file and go!

Code Example

This is how you do CRUD in RedBeanPHP:

This automatically generates the database, tables and columns... on-the-fly. It infers relations based on naming conventions. RedBeanPHP also makes it very easy to work with trees in databases:

RedBeanPHP uses recursive table expressions to deal with tree structures in your database to improve performance (to use this feature you need a database that supports RCTEs like MySQL 8.0.1+, MariaDB 10.2.2+ or PostgreSQL 9+). Learn more about RedBeanPHP trees.

In RedBeanPHP 5.3 and higher you can use R::useFeatureSet( 'novice/latest' ) to automatically select the latest features. If you are working on an older code base you can ommit this line. The latest keyword means that you want to use the latest features. The novice keyword means that some dangerous features like R::nuke() will be turned off. You can also specify a specific RedBeanPHP version like 5.3 (minimum).

Zero Config

No verbose XML files, no annoying annotations, no YAML or INI. Zero Config. Just start coding.

Fluid Schema

During development, RedBeanPHP will adapt the database schema to fit your needs, giving you the NoSQL experience. When deploying to production servers, you can freeze the schema and benefit from performance gains and referential integrity.
RedBeanPHP offers the best of both worlds!

Powerful

RedBeanPHP features: auto-discovery of models, fast trees, deep copying and smart import.
Write less, do more!

Compatible with PHP 5.2 - 8.5!

RedBeanPHP strives to support all ALL Free, Open Source databases.
Currently, RedBeanPHP supports: MySQL, MariaDB, SQLite, PostgreSQL, CUBRID and Firebird/Interbase***. RedBeanPHP supports PHP version HHVM, 5.2**, 5.3.0-5.3.2**, 5.3.3, 5.4, 5.5, 5.6, 6.0*, 7.0, 7.1, 7.2, 7.3, 7.4, 8.0, 8.1, 8.2, 8.3, 8.4 and 8.5 We take backward compatibility very serious! RedBeanPHP has a track record of 20 years of PHP language level compatibility without a single breaking change! You can trust RedBeanPHP.
*=partial (according to community)
**=requires patch
***=experimental

Quality Software

The library has been created in 2009 and is now considered quite mature. No major bugs have been found since 2013 and only minor features have been added in recent years. The code base is being tested with every change, there are over 20338* unit tests (100% code coverage) for PHP 5.3-latest and all supported databases. The project is actively maintained and we take backward compatibility *very* serious. The code is well-documented. RedBeanPHP is trusted by many developers worldwide and has over 2.1 million installs on packagist alone! (since 3.5) and more than 2k stars on github, furthermore thousands of projects have RedBeanPHP as a dependency. Signify keys and checksums are provided.
*=running the full (!) unit test suite

Download

Download the easy-to-use one-in-all package, one single file containing the entire RedBeanPHP library! No composer, no auto-loaders, no configuration, just download and run! Go to the DOWNLOAD page and download to latest version of RedBeanPHP!

Github repository: RedBeanPHP on Github.
Travis-CI Test Dashboard: RedBeanPHP on Travis.
API Documentation: RedBeanPHP API Documentation.
Community Forum: RedBeanPHP Community Forum.

Your logo on this website?

Notice something strange? There is no cookie dialog on this site! That's because I don't track you in any way. I fully respect your privacy and I want to offer you a high-quality website without annoying ads. So, no ads, no cookies, no tracking pixels, no MBs of Javascript, not even server-side tracking, nothing! That keeps this website clean, very fast, secure and comfy to use. Hell! I don't even know how many visitors there are on this site! To help me keep this website this way, please consider becoming a sponsor of RedBeanPHP and have your company logo on the website! Contact me for more information.

RedBeanPHP is written by BDFL Gabor de Mooij and the RedBeanPHP community.

Download

Welcome to the Download page of RedBeanPHP. Here you can download various editions of RedBeanPHP.

RedBeanPHP ships as a single, all-in-one tarball, that's all you need to get started with RedBeanPHP. Simply extract the tgz file to the destination folder and include the rb.php file in your PHP script.

For a list of new features, fixes and changes in the latest version, please consult the changelog.

Did you check the system requirements?

Download RedBeanPHP 5.7.X LTS  recommended

The latest stable version of RedBeanPHP. If you're new to RedBeanPHP this is the recommended version to use.

After downloading and extracting the file and include the rb-file in your PHP script.

• Download RedBeanPHP 5 all-drivers
• Download RedBeanPHP 5 mysql
• Download RedBeanPHP 5 postgres
• Download RedBeanPHP 5 sqlite

...also see the changelog for details!

Verify your download

Here are the sha256sum outputs of the files:

85a7d1482912be263afe29e069cbbdcf2d64b7e07c961b060e5ea481ca8cf4b8  RedBeanPHP5_7_6-mysql.tgz
84d47122b2d2e049f4ac20bae5a31107ae71ed6e886b0c7d1981d5ee344afe7c  RedBeanPHP5_7_6-postgres.tgz
1e938c18b3f87daba85ad0e8c6eb8fad3154de567dc2bcf88bb894c0a72ba4d4  RedBeanPHP5_7_6-sqlite.tgz
629233b5a60229c0e4c6630114bed6075139de9c100070ced689b36a8e6c1719  RedBeanPHP5_7_6.tgz
signify key: 
untrusted comment: signify public key
RWSEPjwPrf4jAtahiV/HNXWz83QYsppKn0EzVOhsoVV24gwB6mGpsdXL

Always make sure you check the sha256sum before including the file. Also make sure to check the signature!

Check RedBeanPHP Signature

Copy my public Signify-key from the above output and store it in a file called red.pub. To download and check the RedBeanPHP Signature in one go, use:

RedBeanPHP packages are signed using the OpenBSD Signify software (Linux version, macos version, Windows version).

If you use PHP 5.3.3 or older, run the P533 patch first. Download the P533-patch for old PHP versions.

Old versions

It's still possible to download older versions of RedBeanPHP from the RedBeanPHP Download Archives. Feel free to visit the download archives and find one of the previous versions of RedBeanPHP.

I no longer answer questions regarding RedBeanPHP 4 and older. These versions have been deprecated since January 2021.

Quick Tour

In this Quick Tour we will show you how to use RedBeanPHP and highlight some of its features.
Because your time is precious, the Quick Tour is very brief and should only take about 5 minutes to walk through...

Quick Tour in 10 seconds

Have an associative array in PHP? You can store an entire array structure (even from a form) in one line:

This creates a book table with one entry called 'My Book' and a related page (using proper foreign keys). ...8...9...10. :)

Quick Tour in 5 minutes... minute 1:

To begin with RedBeanPHP, download the package from the website and put in somewhere in your PHP project (check the signature).

Now, before you begin you have to include RedBeanPHP in your project, to do so, add a line like this:

Minute 2: Create a database

Now you have to setup your database connection.
If you just want to play with RedBeanPHP you may also use:

This will create a simple, temporary SQLite database, after rebooting your system this database will be gone.

For Windows users: make sure PHP has write access to C:\Windows\Temp.

If you want to start using RedBeanPHP for real, you can connect to a MySQL database like this:

Minute 3: Beans

Now you're ready to start using RedBeanPHP. RedBeanPHP makes it really easy to store stuff in the database. For instance, to store a blog post in the database you write:

Now, RedBeanPHP will create a table called post for you in the database and add a column called title, big enough to hold your text.
The store() function will also return the primary key ID of the record, which we capture in the variable $id.

RedBeanPHP automatically creates a column for your property, in this case 'title'. RedBeanPHP determines the column type by scanning the value in the property. For instance in this case the value is a small text, so RedBeanPHP will add a column of type VARCHAR (assuming this is a MySQL/MariaDB database). Imagine you store a large text in this property later, then RedBeanPHP will change the column type to TEXT to make room for the new value. This is called fluid mode. In fluid mode, RedBeanPHP will adapt the database to meet the requirements of your app. It will never throw away columns though nor will it ever shrink the size of a column, so you don't have to worry about data loss. If you want to clean up your database by removing columns you have to do this manually. Some datatypes are immutable, for instance if you store an ISO date string in a property (2005-01-01), RedBeanPHP will create a date column for you. However in this case, the date column will not change (to TEXT for example). This is because we consider it unlikely you ever want to change a date column into something else (like a TEXT column). If you try to put an invalid date string into this column RedBeanPHP assumes it's by accident.

Note that you don't need any configuration to make this work. RedBeanPHP is configurationless, everything just works out of the box. You also don't need to configure paths or autoloaders because everything is just in one file!
You don't even have to instantiate an object, all methods in RedBeanPHP are static.
Just type R:: and then the name of the method you want to use!

To load the post you just saved, just pass the ID to the load function:

If you want to lock a bean while loading it, so nobody can change the record associated with your bean until your transaction completes use R::loadForUpdate()/R::findForUpdate() instead (version 5+).

You can also use SQL snippets like ' for update ' with operations like R::find() and R::batch(). Before invoking these commands just set the SQL snippet you wish to use:

R::getWriter()->setSQLSelectSnippet( ... );

Yep, there's your post again. To echo the title of your post:

Nothing fancy there, but did you know beans can also be treated like arrays ?

To delete your post, pass it to the trash method:

Now, the post is gone, it will no longer be available in your database.

Minute 4: Finding stuff

Finding stuff in the database is easy:

This will search for all posts have the word 'holiday' in the title and will return an array containing all the relevant beans as a result. As you see, we don't use a fancy query builder, just good old SQL.
We like to keep things simple.

Besides using the find() functions, you can also use raw SQL queries:

Minute 5: Relations

RedBeanPHP also makes it easy to manage relations. For instance, if we like to add some photos to our holiday post we do this:

Here, $photo1 and $photo2 are also beans (but of type 'photo').
After storing the post, these photos will be associated with the blog post.
To associate a bean you simply add it to a list. The name of the list must match the name of the related bean type.
So photo beans go in:

$post->ownPhotoList

comments go in:

$post->ownCommentList

and notes go in:

$post->ownNoteList

See? It's that simple!

To retrieve associated beans, just access the corresponding list:

In the example above, we load the blog post and then access the list. The moment we access the ownPhotoList property, the relation will be loaded automatically, this is often called lazy loading, because RedBeanPHP only loads the beans when you really need them.

To get the first element of the photo list, we simply use PHP's native reset() function...

Although no SQL is necessary, RedBeanPHP is very SQL friendly. For instance, suppose some of your posts have quite a big photo collection associated with it and you want to limit the number of photos to a maximum of 3:

See? Just pass a little SQL Snippet!

Final note

As you have seen, RedBeanPHP dynamically changes the structure of the database during development. This is a very nice feature, but you don't want that to happen on your production server! So, before deploying your app, be sure to freeze the database by adding the following line just below the setup:

Before you deploy, review your database schema. RedBeanPHP tries to make a good database schema for you, but you might want to improve it.
Maybe you added a column you no longer use, or you want an extra index.
Always make sure you review the final database schema before you put it on a production server!
After freezing the database, RedBeanPHP will no longer change the structure, so you have the best of both worlds. NoSQL-like flexibility during development and a reliable schema on your production server!

This was just a quick tour, showcasing some basic usage of RedBeanPHP. For more details please explore the documentation on this website!

Requirements

Short version first... minimal requirements

• GNU/Linux, BSD, Windows, macOS
• PHP 5.3.0 or higher (PHP 5.3.4+ recommended)
• PDO plus driver for your database
• Multibyte String Support

PHP versions

RedBeanPHP requires PHP 5.3.4 or higher. RedBeanPHP is works on both ZEND PHP and HHVM.
RedBeanPHP also works with PHP 7. You can also use RedBeanPHP with PHP 5.3 - 5.3.3, just make sure you run the p533 patch first. PHP 5.2 and earlier are not supported by RedBeanPHP. If you happen to work with PHP 5.2 or earlier it's recommended to upgrade to a newer version of PHP.
PHP 6.0 is also not supported, since this version has never been officially released. Still, some people have been e-mailing me about PHP 6.0. Although RedBeanPHP officially does not support this version, it is said to work 'reasonably'.

Environment

RedBeanPHP works on all well known operating systems, including GNU/Linux, BSD and Mac OSX.
You need to have PDO installed and you need a PDO driver for the database you want to connect to. Most PHP stacks already take care of this.
RedBeanPHP also requires the MB String extension, once again, chances are, this is already there.

Databases

RedBeanPHP supports all well known, open source, relational databases. Official support is provided for: MySQL, MariaDB, PostgreSQL, SQLite, CUBRID and Firebird/Interbase (experimental). Support for other databases might be provided by 3rd parties.

MySQL Strict Mode

RedBeanPHP does not work with MySQL strict mode. To turn off strict mode execute the following SQL query:

Existing schemas

RedBeanPHP has been designed to build your database on-the-fly, as you go. Afterwards, you can manually change the schema to suit your needs (change column types, add additional indexes). Remember that the purpose of RedBeanPHP is to have an easy, configuration-less ORM. This can be achieved only by respecting certain conventions.

Ready to download?

Did you check your system requirements? Proceed to download RedBeanPHP.

Install

Installing RedBeanPHP is very easy. First of all, you need to download the tarball from our server. Just head over to the download section and click on the download link to start downloading the package. You can also use a tool like wget of course.

Simple installation

This will automatically download RedBeanPHP, verify the signature and (see download page) and extract the contents of the package.

RedBeanPHP is always distributed as a TGZ package, also known as a 'tarball'. To extract the contents of this package use:

You'll then see...

OPTIONAL Check integrity:

Now compare the output of that command with the SHA signature shown on the download pages.

OPTIONAL Check authenticity (public keys available on download page and groups forum):

Inside the package you'll find a license.txt and a rb.php file. The first file contains the license information. The second file is the compiled RedBeanPHP all-in-one script. All RedBeanPHP code has been combined into a single file for your convenience.

Including in your project

To include RedBeanPHP in your project, simply copy the file to a location somewhere inside your PHP project and then use the PHP 'require' command to load it:

You are now ready to use RedBeanPHP!
Let's try to setup a database connection!

Patch for PHP 5.3.3 and earlier

This patch is only required for people using old versions of PHP, i.e. PHP 5.3.3 or earlier. If you are running a PHP instance with a higher version number please skip this section. People using PHP version 5.3.3 or older should run the p533patch.php file first and then include the newly generated rb-p533.php file. The patch will modify the source for compatibility with these older PHP editions. Use the patch like this:

You will now see the following output:

After running the patch, you'll see a new file in your folder:

This is the file to be used with your version of PHP.

Composer

Composer is not the preferred way to install RedBeanPHP and never will be. Using package management systems for development can be dangerous because people can inject malicious dependencies or remove dependencies. Related news items:
Malicious code snuck into in Python repository
The "Left-pad" incident at NPM
Arch-linux incident

To install RedBeanPHP with Composer... Just open your composer.json file and add the package name (e.g. "gabordemooij/redbean": "dev-master") in your require list.

..for more details on Composer based installation see the readme on github.

Connection

To connect to an SQLite testing database, without having to make one yourself, use:

On most systems, this just works.
This code creates a test database in your /tmp folder.
Of course, this is meant for testing purposes only (and to fool around), to connect to a real database, use one of the following snippets:

For Windows: make sure PHP has write access to C:\Windows\Temp.

MariaDB

MariaDB (formerly known as MySQL) is the most popular database among web developers. Use MariaDB or MySQL for light web development. To connect to a MySQL database or a MariaDB database:

Did you manage to establish a connection to the database? Proceed to learn the basics of RedBeanPHP!

Did you receive a connection error?
Note that PDO errors are not passed to the client as under certain circumstances they can reveal secrets (such as passwords). To see exact error messages you must create a direct PDO connection without RedBeanPHP. A sample is shown below:

PostgreSQL

Postgres evolved from the classic Ingres database and is by far the most advanced database you can get. Use Postgres for serious application development. Postgres is rock solid and has lots of power features like window functions, support for hierarchical queries and materialized views. To connect to a PostgreSQL database:

SQLite

SQLite is file based database, ideal for embedded applications, prototyping, small (and smart) applications, small websites (not too much traffic) and data analysis. To connect to an SQLite database:

CUBRID

CUBRID is an exciting database platform focusing on web development. It's an ideal replacement for rusty MySQL servers. While CUBRID seems to be almost completely compatible with MySQL it also offers a great deal of advanced features, like hierarchical queries and click counters. However, CUBRID also offers a very complete, easy-to-use GUI based toolchain. To use the CUBRID database with RedBeanPHP4, first install the plugin pack. To connect to a CUBRID database:

Closing

To disconnect use:

This will close the database connection.

Tutorial

In this tutorial we're going to write a little application to demonstrate some basic features of RedBeanPHP. Instead of a boring todo app, we'll write a little application to manage whisky tasting notes. We call this application 'dram' which is 'a small glass of whisky'.

The Environment

We'll build a CLI application. This means we don't create a graphical user interface. Our application will run on the command line. This allows us to focus solely on the program code without having to bother with things like HTML templates. We also assume you're using a UNIX or GNU/Linux operating system.

Step 1: Setup

First, we need to download and install the RedBeanPHP package. Luckily, this is a no-brainer. RedBeanPHP is distributed as a single file which we just grab from the internet like this:

Here we download the RedBeanPHP package from the RedBeanPHP servers. We then extract the contents of the tarball. RedBeanPHP is always distributed as a single tarball containing the single code file. The code file inside the tarball is named:

For this tutorial, we'll use a temporary database, so after rebooting your system, the data will be gone.
While not very practical in real life, this is ideal for testing and playing with RedBeanPHP. So, let's create our application, the dram.php file:

...and we're going to edit it using our favourite editor...

I like to use VIM but that's of course just a matter of choice. Any plaintext editor would do fine of course.
Now, let's require the RedBeanPHP library file and setup our database connection:

That's all, we're now ready to start coding now.

Step 2: Let's add a bottle of whisky

When working with RedBeanPHP, it's important to start by creating records first. So first write your logic for adding records to the database. Some people like to begin by creating an overview page listing all the records in a table, however this means your database must already contain at least some data.
Since we like RedBeanPHP to do all the heavy lifting for us, including table and column creation, we better start the other way around, by adding records. So, always start with your 'add' code.

We use the getopt() function of PHP to read commands from the console.
In this case we listen for two commands: add and list.
Now let's see how we add a bottle of whisky to our collection:

This code works very simple: it takes the value of the add parameter from the command line and creates a new bean of type whisky. It then puts the text in the name property of the bean and stores it. To make it possible for our users to view the whisky menu we also implement a list feature:

We can now use the application like this:

...and to view the list...

That's already quite a fancy application in just a couple of lines. But we can do more! However, before we continue, let's take a look at the database. Before we began, it was empty, but now we see this:

We see the whisky table has been created. The required columns are there as well:

RedBeanPHP creates the necessary tables and columns automatically. The type of the column in the database depends on the value you want to store in it. RedBeanPHP scans the value you want to store in a column and makes sure the column has a type that can contain your data properly. You can always tune your database schema manually of course.

Step 3: Throwing bottles away

We are now going to add a new feature: 'delete'. Not suprising, the delete command will remove a specific record from the database. First we add the 'delete' command to getopts, so our application can recognize this command:

Next, we write a little code to perform the actual deletion:

Nice, so we can now add, list and delete whiskies! Let's give it a try!

Oops, a typo, it's Dailuaine not Daluaine. A delicious whisky by the way. Thanks to our new delete function, we can now remove this faulty record and correct our silly mistake:

Now this is all nice and fun but where are the notes? It's supposed to be a tasting notes app after all? So, let's add the notes before the Haggis gets cold!

Step 4: Adding some tasting notes

Let's first consider the relation between a tasting note and a bottle of whisky. A whisky bottle can have many tasting notes, yes? Right, so what about the other way around? Can one tasting note belong to many whiskies? Unlikely, since we consider every whisky to have a unique taste (except the very cheap stuff maybe).
This means we need a one-to-many relation here.
One whisky has many notes, each of these notes belongs to one whisky. This kind of relation is sometimes expressed as: 1-N. Now, when we throw away a bottle of whisky because we are no longer interested in it, should we keep the corresponding notes? No! of course not! The notes themselves are not of any interest, they only matter in relation to the whisky they describe. This means we have to use an exclusive own list: xownNoteList. We relate the note and the whisky like this:

Note that the name of the list contains the type of bean we're storing in it. This is by convention. The format for a list is:

So if we want to store pages in a book we use ownPageList. Because we want to throw the notes away with the bottle, we use an exclusive list. Therefore we begin the name of this list with an 'x'. Once an exclusive list has been defined, there is no way back. If you want the notes to stay after all, you'll have to open your database management tool (phpmyadmin) and change the foreign key setting.

Now, let's make a feature for our users to list all the notes attached to a certain bottle of whisky:

Step 5: Wrapping up

Now let's take a look at the whole application, here is my version:

Here is how to use it:

Step 6: Playing with models

Just for fun, we're going to add a model. In many web application using the MVC pattern, models are used to encapsulate the business rules. Now let's say we don't accept tasting notes containing less than four characters. This qualifies as a business rule in the drinking business :). To add this validation rule we need to have a model. In most object relational mappers this is why you have to create a whole class first. In RedBeanPHP we like to things a little different. We have no models remember? Just beans. So, how do we go from a bean to a model ? Simple, we just add a model and RedBeanPHP will automatically detect its presence. Based on the naming convention it will connect the model to the bean. Here we go:

You can also use \RedBeanPHP\SimpleModel.

Within the note model we can refer to our bean using:

The update() method will be invoked by the bean once we try to store it. There is no way to stop the code flow though, to prevent RedBeanPHP from storing the bean we have to throw an exception, or issue a die() statement. Let's test it:

Nice! That works really well! See? We did not have to change our code, simply add models whenever you like. No need to take all your code, put it in a class or add validation rules here and there, no, just add the model and suddenly all actions will flow through it. Besides update() we can use a lot of other 'hooks' to do all sorts of model stuff.

Step 7: Freezing

Before we deploy our application, we need to review the database and freeze it. To freeze the database we simply invoke the freeze() method on top of our code, just below the setup line:

That's it, we have our whisky app!
Of course there's much more to RedBeanPHP than just doing CRUD and one-to-many relations, but it's nearly impossible to fit all those features in a single tutorial.
Feel free to extend this little app with tags, categories and other concepts to explore all the other features RedBeanPHP has to offer. Enjoy!

Videos

Besides the Quick Tour and the Tutorial there are also a lot of video tutorials about RedBeanPHP on the web. Here is a selection. Did you create a useful screencast on RedBeanPHP? Just drop me a link and I might add it here.

Note: these videos are hosted on external sites. Upon clicking on one of these videos you will be taken to an external site.

Have you created a RedBeanPHP video? Just notify me and I'll put it on this video page as well!

CRUD

CRUD stands for Create, Update, Retrieve and Delete. CRUD operations are the core of many web applications.

Working with beans

RedBeanPHP works with beans. Most interactions with the database are accomplished using beans. Beans are used to carry data from and to the database.

Every bean has a type and an ID. The type of a bean tells you which table in the database is used to store the bean. Every type maps to a corresponding table. The ID of a bean is the primary key of the corresponding record.
You can create a new bean by dispensing one.

Create

To create a new bean (of type 'book') use:

You can now add properties:

You can also use array notation if you like:

and store the bean in the database:

At this point, the bean will be stored in the database and all tables and columns have been created.
The bean will now have an ID, which is also returned for your convenience.

RedBeanPHP will build all the necessary structures to store your data. However custom indexes and constraints have to be added manually (after freezing your web application).

TIP: If you start building an application with RedBeanPHP, the easiest way is to start with the add/update form, use R::load(bean, id) to either create (0) or update a record (id != 0) with a single form! Then use R::find() for the overview (in fluid mode it will not throw exceptions if the table does not exist yet). You can also use a special install url to prepare the database or take a look at RedSeed.

Conventions

You can dispense any type of bean you like, as long as the type name consists of lowercase alphabetical characters:

However dispense also offers some shortcuts:

Properties of beans may contain alphanumeric characters and underscores. Camelcased properties will automatically convert to snake_case:

Do not use field names ending with _id, these are reserved for bean relations. Learn more... Other restrictions:

• primary key need to be "id"
• do not name a field "field" if a field "field_id" exist (because of a bean relation)
• do not name a field "field_id" if it's not a foreign key

Retrieve

To load a bean, simply pass the type and ID of the bean you're looking for:

If the bean does not exist an empty bean with ID 0 will be returned.

By default RedBeanPHP returns only strings, to change this use: R::getDatabaseAdapter()->getDatabase()->stringifyFetches( FALSE );
For MySQL you also need:
R::getDatabaseAdapter()->getDatabase()->getPDO()->setAttribute(PDO::ATTR_EMULATE_PREPARES, FALSE);

Locking (version 5+)
If you want to lock a bean while loading it, so nobody can change the record associated with your bean until your transaction completes use R::loadForUpdate() (version 5+).

It's also possible to attach other kinds of SQL snippets along with the loading function, for instance to make use of the lock-in-shared-mode feature of a database, you can attach a snippet like this:

R::load('bean', 1, 'LOCK IN SHARED MODE');

You can also use SQL snippets like ' for update ' with operations like R::find() and R::batch(). Before invoking these commands just set the SQL snippet you wish to use:

R::getWriter()->setSQLSelectSnippet( ... );

Load Exceptions (version 5+)
If a bean does not exist, R::load() and R::loadForUpdate() will return an empty bean.

If there is an error because of a missing table or column, both methods will return an empty bean in fluid mode and throw an exception in frozen mode.

If something else happens (lock timeout for instance) both methods will always throw an exception, even in fluid mode*.

*except for SQLite, because in fluid mode it's too difficult to separate error types.

Update

To update a bean in the database, add or change properties:

Note that we added a new property 'published', RedBeanPHP will add a new column of type 'date' for this property. Also, it will widen the 'rating' from INTEGER to VARCHAR to support text as well as numbers.

If you want a suitable data type of monetary values, use the 'XX.XX' format and you'll get a fixed precision number data field. To make use of Postgres special purpose, currency-aware money data type, prefix the value with a common currency symbol.

You might want to tweak ini_set('precision', ...) to set the number of significant digits displayed in floating point numbers.

You can use R::isoDate() and R::isoDateTime() to generate the current date(time) if you like. DateTime object are automatically converted to strings.

As of RedBeanPHP 5.7.2 you can tell RedBeanPHP to automatically return a property value as an object (like DateTime) using the asClass() method, where 'Class' is the class you want to use to wrap the value in:

As of RedBeanPHP 4.1 you can also use spatial columns for MySQL, learn more.

As of RedBeanPHP 5 you can now use JSON columns. Arrays in bean properties will be automatically converted to JSON strings and the database Query Writer will automatically adjust the column type to JSON for you. To enable these features use: R::useJSONFeatures(TRUE); (by default these features are NOT active). JSON support should be considered experimental at this stage. JSON support is still very new, check whether your DB version supports this.

RedBeanPHP will dynamically add new columns to your database. It determines the column type to use by looking at the value you are trying to store. For instance, a short text might be stored as a VARCHAR while a large text might be stored as TEXT. Similarly, a boolean value will probably get stored as TINYINT but when you put a float in that property the column will probably be changed to FLOAT or DOUBLE (depending on your database).
Some column types behave differently, for instance if you store a valid ISO formatted date (i.e. 2015-01-01) RedBeanPHP builds a DATE column, but this column will not change. In general, RedBeanPHP tries to adapt the database to your application. If you're done developing, you can freeze the database using the freeze() function. After that, the database schema will no longer change (because it is very unlikely you want to store something other than a date in a column you filled with perfectly formatted date in the first place).
Note that RedBeanPHP will never throw away columns or 'shrink' columns (from TEXT to VARCHAR) to avoid data loss. RedBeanPHP also only manipulates column types it recognizes, so if you change a VARCHAR(255) to a VARCHAR(254) it will leave that column alone, since it no longer recognizes the type. This means that if you customize columns, RedBeanPHP leaves them alone from that point on.
If RedBeanPHP alters the database in a way you don't like, don't worry, you can always tune the schema to your liking (just use your database management tool or phpmyadmin), you can even freeze certain tables only.

Delete

To delete a bean:

To delete all beans of a certain type:

To destroy the entire database simply invoke the nuclear method (be careful!):

Batch

To load a series of beans use:

This will load all beans of type 'book' that have their id listed in the $ids list.

trashBatch (5.1+)

Similarly, you can use trashBatch to delete an entire collection of beans in one go:

Reload

To quickly reload a bean:

Finding Beans

Instead of loading beans, you can also use the find() method to search for beans using certain criteria. Learn how to query beans in RedBeanPHP.

Finding

If you do not know the ID of a bean, you can search for beans using the find method:

The find() method uses good old SQL. No fancy, custom query language — just plain old SQL.

The find operation in this example returns all beans of type book having a rating of four stars or more.

Find and SQL

The following example demonstrates how to use find() with bindings.

This find operation will return all beans of type 'book' having a title that begins with the phrase: 'Learn to'.

If find() has no results it will return an empty array.

There is no need to use mysql_real_escape. Always use the bindings.

PDO bindings do not work for tables (see discussion here), however if you wish to escape a table name you can use: R::getWriter()->esc( $tableName ).

Never put user input directly in your query!

Hunting Beans (5.1+)

To find and delete beans in one go:

As of RedBeanPHP 5.2:
returns the number of beans deleted.
the SQL parameter is optional.

IN-queries

To use a 'SELECT-IN' style query use the R::genSlots function to generate the correct number of '?' slots:

Find One

If you want a single bean instead of an array, use:

If no beans match the criteria, this function will return NULL.

As of 5.3 you can use explicit parameter binding if you like:

As of 5.6.3 you can use pstr( $str ) to generate [ $str, PDO::PARAM_STR ] for you and pint( $num ) to generate [ $int, PDO::PARAM_INT ] - these are just shortcut functions for your convience.

Find All

Use findAll if you don't want to add any conditions (but you want to order or limit... )

If no beans match your criteria, this function returns an empty array.

Named slots

All find methods: find, findOne and findAll also accept named slots:

Besides querying beans, you can also use regular SQL queries.

Cursors (4.2+)

You can also use find with cursors:

Or directly

The advantage of using a cursor is that the entire collection will not be loaded into memory all at once. This is handy for dealing with large bean collections.

Find like (4.2+)

To find a bean matching certain criteria, you can use R::findLike(). The following code returns all flowers that are either yellow OR blue:

Note that you can append some SQL here along with bindings.

As of RedBeanPHP 5.2 you can also use beans as conditions:

Find or create (4.2+)

This works like R::findLike() but also creates (and stores) the bean if it does not exist yet...

Find Multiple (4.2+)

findMulti() takes a query and turns the result into several bean collections having different types:

The first parameter of this function lists the types to load, the second parameter is the query, then come the optional query parameter bindings. The result of this operation will be something like:

Besides loading various bean types at once from a query, this method can also restructure them, for instance to 'put the pages in the book' use (example of 4th parameter):

The fourth parameter of findMulti takes an array containing arrays like the one above. The array in the example tells findMulti how to restructure the pages and the books. First it defines two variables 'a' and 'b' it then defines a matcher function, telling RedBeanPHP to execute the 'do' clause if the book_id of a page matches the id of a page. The 'do' clause then puts the page in the pageList of the selected book. While you can specify mappings like this, a better idea might be to write your own set of mapping functions returning structures like this.

Finder::map helpers (5.3+)

You can shorten the syntax above using the mapper helper:

Use Finder::map to map the price data and the products to the shops. Finder-helpers like map() will return a mapping structure like described above, consisting of an array with a/b entries as well as a matcher function and a do-function. Use map() to map 1-N relations (one shop, many products), use onmap() to map N-1 relations (many users belong to one country) and use nmmap() for N-M relations (many books share many tags).

Short Query Notation (SQN)

If you wish to use a shorter syntax than SQL you can try my short query notation library. Example:

As of RedBeanPHP 5.2 bean type names will be trimmed automatically.

As of RedBeanPHP 5.2 the SQL parameter is optional.

loadJoined() 5.5

As of RedBeanPHP 5.5 you can use Finder::onmap for N-1 relations:

But you can also use the loadJoined() shortcut:

Don't access parent beans in loops, that is bad for performance. With 100 users the following code will run 101 queries:

$users = R::find('gebruiker');
foreach($users as $user) $user->country;


Instead use:

$users = R::find('gebruiker');
R::loadJoined($users, 'country');
foreach($users as $user) $user->country;

This will only run 2 queries.

Even better: If you want to display a list or report, extracting information from various beans, consider using plain sql instead (R::getAll()).

Querying

Querying the database manually is also possible with RedBeanPHP. You can use the SQL query functions provided by RedBeanPHP. To execute a query:

To get a multidimensional array:

The result of such a query will be a multidimensional array:

Note that you can use parameter bindings as well:

To fetch a single row:

To fetch a single column:

And finally, a single cell...

To get an associative array with a specified key and value column use:

In this case, the keys will be the IDs and the values will be the titles. getAssocRow will return complete rows.

For dynamic queries use R::getWriter()->esc() & R::getPDO()->quote()

In my examples, I like to use the short array notation.
In PHP < 5.4 you'll have to use the classic array notation:

array( 'key' => 'value' ).

Get the insert ID (4.2+)

To get the ID after an insert in MySQL/MariaDB compatible databases use:

Converting records to beans

You can convert rows to beans using the convertToBeans() function:

As of version 4.3.2 you can also use: R::convertToBean, without the s, for single rows.

Find from SQL (5.6+)

As of version 5.6, you can create beans from an SQL in one go, using the additional Facade convenience method findFromSQL.
Usage (Postgres dialect):

This style of querying might be handy for finding beans along with pagination data to paginate results properly (in this case the OVER-clause only works with Postgres). You can use the info() method on a bean to access the meta data.

Remember:
There is no need to use mysql_real_escape as long as you use parameter binding.

Besides querying you can also use other database functionality (like transactions) in RedBeanPHP. Learn more about database functions.

Extended SQL

As of RedBeanPHP 5.5 you can use some SQL extensions besides @joined, and you can use those extensions with almost any RedBeanPHP function that accepts an SQL snippet.

@joined

Use @joined to access parent beans directly in SQL:

@own

Use @own to access own-lists in SQL:

@shared

Use @shared to access shared-lists in SQL:

Chaining

SQL-extensions also work with CTEs (trees) and you can chain them.

In the tree-query above we use multiple SQL-extensions together and we also chain them, @joined.author.shared.role.label will access the author parent beans and then check the label associated with its shared role. You can make it as complex as you wish. Under the hood, RedBeanPHP translates these @-lists to JOINS.

Aliasing in SQL-extensions

Use aliases in SQL-extensions as follows:

This will find any book written by Bob, checking the name using the author-property of the bean instead of the person property. You can also use aliases for own-lists:

Separate multiple aliases with a slash:

Note that the word in front of the colon (as:) is only there for yourself as a reminder, RedBeanPHP figures out how to use the alias depending on the type of list you access. Of course you can chain aliased items as well:

Vias in Extensions

To treat an intermediate bean type or two complimentary N-1 relations as as a N-M relation in SQL, you can use the via-operator as well:

These features can also be used in $books = $author->withCondition( SQL ) - context.

Data Tools

In RedBeanPHP version 5, some additional functions have been added to increase your productivity even more. These are convience functions building upon the solid foundation of RedBeanPHP, allowing you to quickly perform a lot of work with just a single command.

Look (5+)

To quickly generate template snippets that rely on database data you can use Look:

Given the colors red, green and blue, this code will return an HTML snippet for a select-list with the colors RED and BLUE in uppercase.

MatchUp (5+)

MatchUp is a powerful productivity boosting method that can replace simple control scripts with a single RedBeanPHP command. Typically, matchUp() is used to replace login scripts, token generation scripts and password reset scripts. The MatchUp method takes a bean type, an SQL query snippet (starting at the WHERE clause), SQL bindings, a pair of task arrays and a bean reference.
If the first 3 parameters match a bean, the first task list will be considered, otherwise the second one will be considered. On consideration, each task list, an array of keys and values will be executed. Every key in the task list should correspond to a bean property while every value can either be an expression to be evaluated or a closure (PHP 5.3+). After applying the task list to the bean it will be stored. If no bean has been found, a new bean will be dispensed. This method will return TRUE if the bean was found and FALSE if not AND there was a NOT-FOUND task list. If no bean was found AND there was also no second task list, NULL will be returned. Here is an example of how we could use MatchUp for a typical password-reset script:

I recommend to use the PARAM_STR for tokens to avoid casting related security issues.

CSV Queries (5+)

To quickly generate a CSV file with a single RedBeanPHP command use R::csv() like this:

Diff (5+)

To quickly get the difference between two beans (or arrays of beans) and their relations use R::diff(). For instance, let's create a book with some pages:

Now we change the book:

We can now compare both books using:

If we print_r() that variable we'll see:

The 3rd parameter can be used to set a filter, all bean types in the filter will be omitted. To format the keys set a format in the 4th parameter, the default value (giving us this result) is: '%s.%s.%s'. This is printf-like format.

How to use queries

Sometimes using a plain query is more efficient than using beans. For instance, consider the following example:

Using a plain query this task could be accomplished far more efficiently:

One of the biggest mistakes people make with ORM tools is to try to accomplish everything with objects (or beans). They forget SQL is a very powerful tool as well. Use SQL if you are merely interested in generating reports or lists.

Database

This chapter discusses general database functionality of RedBeanPHP.

Server version (5.6+)

Due to slight difference appearing between MySQL and MariaDB it might sometimes by handy to obtain the database server version string. You can use R::getDatabaseServerVersion() for this.

Reflection

To get all the columns of table 'book':

To get all tables:

Multiple databases

There are two important methods to keep in mind when working with multiple databases: addDatabase() and selectDatabase().
To add a new database connection use R::addDatabase() like this:

To select a database, use the key you have previously specified:

If you used R::setup() to connect to your database you can switch back to this database using:

Transactions

RedBeanPHP offers three simple methods to use database transactions: begin(), commit() and rollback(). Usage:

Because RedBeanPHP throws exceptions, you can catch the exceptions thrown by methods like R::store(), R::trash(), or one of your 'fuse' methods, and perform a rollback(). The rollback() will completely undo all the pending database changes.

If you use caching, don't forget to call R::getWriter()->flushCache(); after rolling back! Otherwise, the database cache might still return old data.

Transaction closure

You can also use this variation:

The transaction() method supports nested transactions.

Note about auto-commits:
Many databases automatically commit after changing schemas, so make sure you test your transactions after R::freeze(true); !

Column Functions (version 4.1+)

As of RedBeanPHP 4.1 you can bind an SQL function to a column. This is useful for wrapping values when reading from / writing to the database.
For instance, to use MySQL spatial data types you need to prepare the columns like this:

While this method has been implemented to support MySQL spatial data types, you can use it for other purposes as well.
For instance, you can encode your own data types, create an encryption function or a UUID function.

As you have seen in the previous chapters RedBeanPHP will keep changing the schema to fit your needs, this is called 'fluid mode'. While this is great for development, you don't want this to happen on your production server. Learn how to freeze your database for deployment.

Query counter (4.2+)

To count get number of queries processed use:

Logging (4.2+)

Logging has always been possible with RedBeanPHP, however from 4.2 on there is an easier way to setup logging:

Partial Beans (5+)

Toggles 'partial bean mode'. If this mode has been selected the repository will only update the fields of a bean that have been changed rather than the entire bean. This method will return the previous mode (TRUE/FALSE).

In RedBeanPHP 5.2+ you can also set the 4th parameter of setup() to TRUE to enable partial beans.

Fluid and Frozen

RedBeanPHP has two modes, fluid and frozen.
As you have seen in the previous chapters, RedBeanPHP will keep changing the schema to fit your needs, this is what we call 'fluid mode'.
While this is great for development you don't want this to happen on your production server. That's why you need to freeze the schema before you deploy your application. To freeze your app, put R::freeze( TRUE ) at the beginning of your script, like this:

After freezing the schema, open your database client and inspect the schema RedBeanPHP has created for you. You can now refine it where necessary, i.e. add some indexes, change some columns, add or change constraints and more.

Always review the schema generated by RedBeanPHP and allow yourself some time to refine it.
Do not change the table or column names though, these are part of the RedBeanPHP conventions. Instead I recommend to inspect and refine column types ( maybe a bit too wide ? ), indexes and foreign key constraint settings.

Partial freezing (Chill mode)

It's also possible to only lock the schemas of several types of beans, for instance to lock the schemas of bean types 'book', 'page' and 'book_page' use:

This makes RedBeanPHP operate in fluid mode, but those tables will not get modified. To reset, pass an empty array.

Learn how to use the debugging tools.

Hybrid Mode (5.4+)

R::store() and R::storeAll() both take a second parameter: $unfreezeIfNeeded. If set to TRUE in frozen mode, RedBeanPHP will automatically temporarily switch to fluid mode to attempt to store the bean in case of an SQLException.

Debugging

The debug() method will reveal all queries being executed by RedBeanPHP:

The queries will be printed on the screen. The output of the debugging function looks like this:

You can also log the queries:

To access the logs:

Use the grep() method to search the logs.

Query parameters

By default, the debugger prints the queries and parameters in separate sections. Sometimes you might prefer to see what the actual query would look like if the parameters had been filled in. RedBeanPHP 4.1+ offers two new debugger modes to facilitate this:

Outputs the query above like this:

Mode 2 also writes to the logs, if you want to suppress screen output, select mode 3.

In 'fancy' mode schema altering queries are highlighted as well as bound parameters. Parameter bindings are also included in the SQL instead of in a separate list. If a parameter value is too long, fancy debug will only show the first part so your query remains readable. Also, fancy debug works with HTML colors as well, in case you like to debug with a browser instead of a command line.

Under the hood

Under the hood, all debugging functionality makes use of the logger classes. There are two logger classes available in RedBeanPHP: the Default Logger and the Debugger Logger (4.1+). Besides using the convenience methods listed here you can create your own logger instance and attach it to some object:

As of version 4.3.2 R::fancyDebug( TRUE ); is the recommended way to debug.

Inspecting Beans

The easiest way to inspect a bean is to just echo it.

If you have a list of beans, an array, you can use good old print_r of course, but print_r will also print useless details. To get a shorter and more descriptive summary of a bean or an array of beans you can use the dump() function:

The output looks like this:

An even shorter syntax:

The dmp() function is a global function for your convenience.

Error handling

Error handling is different in fluid and frozen mode. In fluid mode SQL errors caused by missing columns or tables will be suppressed but other errors (syntax) will throw RedException\SQL exceptions.

SQLite and some plugin drivers do not provide meaningful SQLSTATE codes, therefore under these drivers fluid mode will suppress all errors.

Testing the connection

In RedBeanPHP 4.1+ you can test the connection using a special test function. This function will refrain from throwing exceptions and simply return TRUE if the connection has been established and FALSE otherwise:

Besides debugging, this function is handy for installers and setup scripts of web applications to determine whether database credentials have been entered correctly.

Learn about relations in RedBeanPHP.

One-to-many

In a one-to-many relation, one bean has a list of other beans but all those beans cannot belong to another bean at the same time. For instance, let's create a shop:

To add products to the shop, add beans to the ownProductList property, like this:

Each product in the ownProductList belongs to shop and cannot belong to another shop.

Note that the name of the list has to match the type of beans it contains. So, the 'ownProductList' contains beans of type 'product', a pageList contains pages, an 'ownCarList' contains 'cars' and so on. This convention is used to create the database mapping, in case of the shop, every product record will get a 'shop_id' field.

When you access an own-list, RedBeanPHP will query the related beans and populate the array, this is called lazy loading. So, to load the list:

To remove the products from the shop:

To replace the current list of products:

Be careful with __toString methods in beans, RedBeanPHP uses the string representation of a bean to determine whether it should be added or removed from the list.

Exclusive mode

Note that those products continue to exist in the database, they are just unrelated, don't want that ? Then open the own-list in exclusive mode, using the x-own-list like this:

Emptying the list now will cause the vases to be gone too. In exclusive mode the beans in the list are considered to be dependent on their owner. If they are removed from the list, they are deleted as well (i.e. they depend exclusively on their owner).

When using the x-own-list from the start, if you delete the shop, its products will be deleted as well.

This happens because the first time you access an own-list, a foreign key will be created for the owned bean, one that will CASCADE ON DELETE for an x-own-list and one that will SET-TO-NULL otherwise. Once the foreign key is in place, it will not be modified by RedBeanPHP anymore. However you can always change the constraint manually using your database client.

Other end of the one-to-many

The other end of the one-to-many relation is the many-to-one relation. Learn more about the many-to-one relation.

Many-to-one

Now let's look at this relation from the perspective of a product. A product belongs to a shop, so you can access the shop like this:

This is called the 'parent bean'.
The shop is considered the parent of the product. It owns the product.

Either (5.7.3+)

The PHP ?? operator does not work properly because of lazy loading, you can use either() instead:

The Either object also works with lists and offers a convenient first() and last() method:

Exists (5+)

To check if a related bean exists:

This function will return TRUE if a shop has been associated with the product and FALSE otherwise.

Setting a parent bean

To set a parent bean:

Note that, when you set a new shop the property shop_id still points to the old shop (or is still NULL if there was no previous shop). This field gets updated after the bean has been saved. So, the shop_id and shop fields are not always in sync.

Another way to update the shop is to simply set the new id, once again, shop_id and shop will be out-of-sync until the next R::store().

However if we change the id before we load the shop, the new shop will be loaded:

This may seem a bit weird but it's actually quite logical. When accessing the parent bean, RedBeanPHP simply looks at the value of shop_id and loads the shop identified by that id.

As of RedBeanPHP 4.3.4 the latter behavior has been resolved. Changing the _id property after loading will also sync the loaded bean.

Removing the parent

To remove the shop from our product in the example above, simply assign the value NULL to the property 'shop':

Besides one-to-many, RedBeanPHP has a special version of this relation: the one-to-X also known as the one-to-fixed relation. Read more about the One-to-fixed relation.

Aliases

Sometimes you want to refer to a bean using a different name. For instance, when you have a course referring to a teacher and a student, both of which are people. In this case you can use fetchAs:

fetchAs tells RedBeanPHP the ID has to be associated with a different type (in this case 'person' instead of 'teacher' or 'student'). This also works the other way:

From a relational point of view, we have exactly two people for every row (although one or both can be NULL of course). This is why we call these 'aliases' one-to-X relations (or one-to-fixed relations), where X is a fixed number.
You can use as many of these 'aliases' as you like.

As of 4.2 you can use global aliases. Instead of specifying the alias with fetchAs each time you can specify the alias using R::aliases( ...aliases... ); i.e. R::aliases( ['teacher' => 'person', and so on...] );

Also learn about Many-to-many relations.

Many-to-many

A shared list contains beans that may be associated with more than just one other bean (many-to-many relation). Tags are a common example:

In this example, a product can have multiple tags and every tag in the list can be associated with other products as well. The latter was not possible in the one-to-many relation.

Like the own-list the name of the shared-list has to match the type of beans it contains. In the database, these assocations will be stored using a link table called 'product_tag'.

This link table is cleaned up automatically, if you break the association between two beans in a shared list the link record is removed as well. Also note that a shared list cannot have aliases and always applies a UNIQUE constraint (you cannot have duplicate links). In some situations this means you have to use a slighly different approach; the N11N relation.

Via relations

Using the via() method, you can treat normal beans as if they were N-M relations:

Remember that, since unrelated link beans are removed automatically, emptying a shared list (even using via) causes the link beans to be removed! However, you can always nullify the relations manually of course.

Via is sticky, once you tell RedBeanPHP to fetch a type of bean via another bean it will remember this for the rest of the program. So, once you told RedBeanPHP: $project->via('participant')->sharedEmployee it will always load employees using the participant table as a link table, even if you later say: $project->sharedEmployee. Also note that via() reloads the list.

Self referential N-M

You can have a shared list containing beans of the same type as the owner of the list:

In this case RedBeanPHP will operate in a special self-referential many-to-many relationship mode. It will not only retrieve all friends of $friend, but also all other friends that are associated with $friend.

You can use two complimentary one-to-many relations as one many-to-many relation. This is called an aggregation or N11N-relation.

Using SQL Snippets

You can modify the contents of an own-list and a shared-list using additional SQL snippets. Use with() to order or limit the list and withCondition to add additional filtering.

Note the last case in this example. Here we use a column from the link table to filter the rows. This technique allows you to filter on relational qualifications like the duration of the assignment to the project.

You cannot combine with() and withCondition(). Instead, you can append additional clauses like in the third example.

Important note about AND/OR statements in snippets. If you plan to use AND/OR statements in your conditions, please remember your snippet is integrated into a larger query. For the best results, it is recommended that you put your AND/OR snippets between parenthesis like this:

...->withCondition(' ( deleted IS NULL OR deleted = 0 ) ')...

Via and SQL

Via can be used with SQL snippets as well:

Both with() and withCondition() cause the list to reload, however if the SQL snippet hasn't changed and the writer cache is active (default) then no query will be send to the database.

Reloading a list

To reload a list without an SQL snippet use the all() method or unset it:

Joins (version 4.1+)

Sometimes you want to sort or filter an own-list based on some other property in another bean. You can use the @joined keyword to select such a property and RedBeanPHP will automatically join-in this field:

In the example above, each book has an information bean called 'info' that contains the title of the book and a category bean called 'category'. We like to filter on category and book title - so we use the @joined.info.title and @joined.category.title for the filtering. We also like to order the resulting records, so we add an ORDER BY clause with @joined.info.title (orders on the book title).

The noLoad modifier

Sometimes, when you only want to add something to a list, there is no need to load the entire list. To keep RedBeanPHP from loading a list use the noLoad modifier as depicted in the following example:

This will add a new page to the list, but the initial loading of the list will not take place.

Counting

Counting records is very easy with RedBeanPHP. For instance, to count all beans of type book use:

You can use additional SQL here as well:

Count related beans

Counting related beans is just as simple. To count all the pages of a 'book' bean:

You can use the same technique for shared lists:

You can also use withCondition() and alias():

The first example counts all projects associated with the member in which the member has the 'lead' role. The second example counts all the pages of a book having a page number > 100. Finally the last example demonstrates the use of an aliased list. Here we count the number of books written by Andy where he has been the co-author. All count operations return a number.

Counting something (R::count) that does not exist will not trigger an error but just return the number 0.

Labels, Enums, Tags

Labels, Enums and Tags are all based on very simple beans. These beans only have an id, a type and a name. While they might look simple, these beans can offer various powerful services in your applications. Labels form the basis for enums and tags. Enums are in fact labels in a one-to-many relation while Tags are labels in a many-to-many relation.

Labels

A Label is a bean with just a name property. You can generate a batch of labels of a certain type using:

This will create two meal objects. Each bean will have a name property that corresponds to one of the strings in array.

You can also collect the strings from label beans using:

The gatherLabels() function returns an alphabetically sorted array of strings each containing one name property of a bean in the bean list provided.

Enums

An enum type is a special bean that enables for a property to be a set of predefined values. To use an ENUM:

The ENUM method will do a lot of work here. First it checks whether there exists a 'flavour' bean with the name 'ENGLISH'. If this is the case, enum() will return this bean, otherwise it will create such a bean, store it in the database and return it. This way your ENUMs are created on the fly - properly. To compare an enum value:

To get a list of all flavours, just omit the value part:

To get a comma separated list of flavours you might want to combine this method with other Label Maker methods:

Since RedBeanPHP enums are beans you can add other properties as well. To query using an enum:

The find query above will retrieve all red flowers. While this query is perfectly readable the syntax is a bit clunky, therefore there is a shorthand notation for the R::enum(...)->id part:

The global function EID() returns the ID of the given ENUM directly.

Tags

Tags are often used to categorize or group items. To tag a an item:

To fetch all tags attached to a certain bean we use the same method but without the tag parameter:

To untag an item use:

To get all beans that have been tagged with $tags, use tagged():

To find out whether beans have been tagged with specific tags, use hasTag():

To add tags without removing the old ones:

To get beans that have ALL these tags:

As of version 5.3:
To just count tags use: R::countTagged() and R::countTaggedAll(). Same parameters.

Trees

RedBeanPHP supports self-referential relationships. In RedBeanPHP terminology, these are called trees. Here is an example, let's decorate a christmas tree with some candy canes:

Trees are just a special case of lists, you use a list with the same name as the parent type. In the example script above, a cane has an ownCaneList. Another example: page->ownPageList. As you can see in the example above you can navigate the lists using the IDs.

Traversal

Instead of manually looping through each own-list of a bean you can use the traverse() method:

This allows you to recursively apply a function to a list. To limit the results when accessing a list you can use the with/withCondition() method:

You can also use withCondition and alias together with the traverse function.

Use the third parameter to specify the maximum depth:

Use the PHP use statement to import variables into the function scope:

The traverse() function does not check for recursion in trees.

Traversing upwards

You can also traverse the other way around, here is a quick example:

Importing Trees

Do you want to import a hierarchical data structure ? This can be accomplished using the R::dispense() feature.

Faster trees (5.2+)

If your database supports common table expressions (Postgres, MariaDB 10.3+) you can use the CTE-based tree tools as well:

Given the page hierarchy of the shop above you can use R::parents() and R::children() like this:

Because this approach uses common table expressions the performance is much better.

Caution! This is a new, experimental feature available as of RedBeanPHP 5.2. The CTE API has been tested but may still contain bugs. Also the CTE API may be subject to change in future versions.

Counting in Trees (5.5)

To count beans in trees use R::countParents() or R::countChildren.

As of 5.6 you can add your own SELECT clause like 'count(distinct vendor)'. By default, countChildren() and countParents() subtract 1 from total number of counted records to exclude the starting bean. If you provide your own select clause (or an SQL snippet), this might not make sense, so it won't happen in that case.

Link Beans

The following code associates an employee with a project using a many-to-many relation.

The project and the employee are linked by a link bean. Link beans have their own type, in this case: employeeProject. In the database, these beans are stored in the employee_project table.

Qualified links

Sometimes you want to qualify a relationship. For instance, in the case of projects and employees, you might want to add a 'role' property to the relation:

While this is quite handy, it's often better to introduce the missing concept: participant in this case. Often, when you find yourself qualifying a relationship, you might have missed an important part of your data model. A relation or link is not a very good substitute for this.

Be careful with adding to much properties and logic to relations, make sure you haven't missed an important concept in your domain model.

Accessing link beans

Since a many-to-many relation can be viewed as a combination of two one-to-many relations you can access the link beans through the ownList on either side of the relation. In the case of a project-employee relations you can access the intermediate bean like this:

To remove the intermediate beans upon assigning an empty array open the list in exclusive mode:

Other relations

This chapter discusses less common relations.

Aggregations

It's possible to treat two complementary N-1 relations as one many-to-many relation, thus benefiting from the advantages of a shared list. In RedBeanPHP 4.1+ you can use the aggr() method of a bean to collect the parent beans for each member of an own-list:

This code will iterate over the ownQuestionTargetList and for every questTarget bean in the list it will load the bean in the target property as a bean of type 'quest'. This relation could not have been formed as as shared list because a shared list does not allow aliases. Without aliases the relation would have been a symmetrical one, lacking the notion of direction. Another solution to this problem would be to use the shared list and create a VIEW of quest called target.

One-to-one

One-to-one relations are not used frequently. Traditional 1-1 records are linked by their primary keys. Load them like this:

This loads an author and a biography with the same ID. You need to make sure the IDs are in sync yourself.

In RedBeanPHP one-to-one relations are an anti-pattern, the fields should belong to the same bean. This method has been added for compatibility reasons only, try to avoid it!

Polymorph relations

To load a bean whose type is determined by another column:

This code returns the bean referred to in content_id using the bean type specified in column content_type. If content_type contains the value 'advertisement' the content will be a bean of type 'advertisement'.

This is an anti-pattern in RedBeanPHP, do not use this functionality unless you have to.
Use poly() to retrieve polymorph data from an external or legacy database only.

Models

A model is a place to put validation and business logic. Imagine a Jazz band that can only have up to 4 members. We could implement this rule like this:

However, now we need to add this check everytime we call R::store(). It would be much more convenient if R::store() was smart enough to perform this check by itself. We can accomplish this by putting the validation rule in our model. RedBeanPHP automatically discovers the models that belong to beans, so we can implement this validation like this:

RedBeanPHP automatically connects beans with models using a naming convention (i.e. Model_{TYPE OF BEAN}).
Now, every time we call store and something is wrong with the number of members, an exception will be triggered automatically. The mechanism that connects beans to models is called FUSE, because beans are fused with their models. Within a model, $this->bean refers to the bean.
To create a model for your bean, simply add a class like this:

R::store() will not invoke FUSE-methods if nothing has changed. In fact, store() will do nothing but return the ID if no changes have to be processed.

If you like your models to reside in the namespace \Model, you can set the following constant:

You can now create a model class like this:

If you prefer no namespacing at all:

Beans of types like 'book_page' will search for a model 'BookPage' first and if no such model is found they will try to connect to 'Book_Page'.

As of RedBeanPHP 5.7.2 you can also use different namespaces per database:

Scoping rules

Within the model, the $this->bean variable refers to the bean. Simply $this also refers to the bean but without returning references, in practice this can be very confusing so I recommend to use $this->bean.

Fused methods

Besides update() RedBeanPHP FUSE calls other methods on the model as well: R::store() invokes update() and after_update(),
R::load() invokes open(),
R::trash() invokes delete() and after_delete(),
R::dispense() invokes dispense().

Note that since loading a bean also causes a new bean to be dispensed to receive the record from the database, load also invokes dispense().

Example: all fused methods

To demonstrate the order and use of all of these methods let's consider an example:

output:

Custom FUSED methods

Besides the standard methods mentioned above, any method on the model can be invoked by calling it on the bean (assuming it does not collide with a native bean method):

If you call a method on a bean that does not exist in the bean and also not in the model the call will be ignored. You change this behaviour by selecting a different FUSE error handling mechanism using the setErrorHandlingFUSE() method, see API.

Boxing and Unboxing

If you have a bean and you want to obtain the corresponding model use:

Similarly, if you have a model and you want its inner bean, call:

We call this technique boxing (and unboxing). This can be handy if you want to make use of typehinting:

Otherwise, we would have to use type RedBean_OODBBean which is less descriptive.

Model Factory and Dependency Injection

If for some reason you need to control how the bean turns into a model you can pass a factory function like this:

In this example we inject a mail library in a model using the factory function. For more complex scenarios you can even use the factory to pass the model to your own dependency injection framework.

If you need even more flexibility you can subclass the SimpleFacadeBeanHelper and override the getModelForBean() method.

Use:
R::getRedBean()->setBeanHelper( new MyBeanHelper );
to set the bean helper.

Don't forget to call $this->loadBean( $bean ); in the overridden method to attach the bean to the model. If you use the facade you have to set the bean helper for every database connection.

As of RedBeanPHP 5.2 models can also return jsonSerialized objects by implementing the __jsonSerialize method (will override the default OODB implementation.

As of RedBeanPHP 5.7.2 you can also use the TypedModel instead of the SimpleModel to make use of PHP 8 type hinting features:

Meta data

Beans contain meta data. For instance, the type of the bean is stored in the meta data. To obtain the type of a bean:

You can also store your own meta data in a bean:

this data will not get stored in the database.

Tainted

Some meta data is accessible using convenience method. For instance, if you would like to know whether a bean has been changed since it got retrieved from the database use the tainted() method.

Note that a bean is marked as tainted if a list gets accessed. You can also set the tainted flag yourself.

Old

To determine if a certain property has changed:

These properties will be marked as changed even if you do a R::store(), if you would like to clear the history after every store use:

To manually clear the history of a bean:

To get the old value of the property:

The behaviour of hasChanged sometimes suprises people, for instance take a look at the following code:

The reason for this behaviour is that organisation_id will not be updated automatically until you call R::store(). Until, then the property has not been changed.

List Changed (4.2+)

To determine whether a list has been changed (beans have been added or deleted):

This method will return TRUE if some elements of the array have been removed or added. Note that this method does not check the state of the beans themselves. It's just about the list.

Testing Equality

To test whether two beans have the same type and primary key ID:

Empty

To determine if a bean is empty, or only contains empty values (everything that qualifies as empty() in PHP) use:

Copy meta data

You can copy meta data from another bean like this:

Meta Mask (4.3.2)

As of version 4.3.2 you can specify a meta mask when converting rows to beans:

Here, convertToBeans will put all columns starting with 'meta_' in the meta section of the bean. This allows the query above to select all the fields of the book and query some additional meta data in the process. The meta data from the query will be available under the key 'data.bundle'.

Info (5.6+)

As of version 5.6, you can use info() to access data.bundle values directly:

Duplicate

R::duplicate() makes a deep copy of a bean properly and without storing the bean. All beans in own-lists will be duplicated recursively. All references to shared beans will be copied but not the shared beans themselves. All references to parent objects (_id fields) will be copied but not the parents themselves. The bean will not be stored so you have the chance to modify it before saving. Usage:

As of RedBeanPHP 4, the R::duplicate() method also duplicates trees, in earlier versions the duplication manager skipped tree lists ($page->ownPage). Note that duplication/export won't work for aliased beans.

ID mappings

Curious about the old IDs of the beans that have been duplicated. You can still find them in the meta properties of the copied bean:

Performance

Both dup() and exportAll() need to query the database schema which is slow. To speed up the process you can pass a database schema:

To obtain the schema use:

You can now use this schema to feed it to setTables(). R::duplicate() and R::exportAll() both use this schema.

Filtering

Don't want to duplicate every aspect of a bean? You can pass a white list of bean types to duplicate like this:

The code above only works in RedBeanPHP 4.1. In 4.0 and earlier you have to use R::dup() (see API for method signature).

As of RedBeanPHP 4.1 the R::dup() method is deprecated, use R::duplicate instead, it has a less confusing method signature.

Import and Export

RedBeanPHP offers several functions to exchange data with beans.

Import

You can import an array into a bean using:

The code above is handy if your $_POST request array only contains book data. It will simply load all data into the book bean. You can also add a selection filter:

This will restrict the import to the fields specified. Note that this does not apply any form of validation to the bean. Validation rules have to be written in the model or the controller.

As of RedBeanPHP 5.7.2 you can use trimport() to automatically trim the values. The 2nd parameter of trimport() can be used to define a different function to apply. The rest of the parameters are the same as import().

To import from another bean:

Import using Dispense

Dispense can even convert a multi dimensional array to a bean hierarchy like this (use _type to indicate the type of the bean):

R::dispense() also accepts multi dimensional arrays (4.2+)

Export

To export the properties and values of a single bean use:

To recursively export one or an array of beans use:

Bean lists in exports are keyless, 0 indexed. To also export parent beans:

Because exportAll() does not know about any aliases you have to use R::aliases( [ 'teacher' => 'person', ... ] ) to inform the export function about aliased beans.

Non-static

If you don't like static methods, you can use the objects behind the facade directly. Almost every method of the R-class is available through the original RedBeanPHP objects as well. The facade is just that: a thin layer on top of these objects. Here is an overview of the most important R-methods and how to use them 'the non-static way'.

Note that there are three important objects in RedBeanPHP: the adapter (DBAdapter), the query writer (QueryWriter) and the RedBeanPHP object database (OODB). We call these objects the core objects, because together they represent the foundation of RedBeanPHP. Other objects need these core objects, that's why they are bundled in a toolbox (ToolBox). So, if you need let's say an instance of the Tag Manager class (TagManager) you'll have to pass an instance of the toolbox to the contructor.

Toolbox

You can manually assemble your toolbox like this:

Wiring

RedBeanPHP has a very decoupled architecture, which makes it very flexibile. However this means you need to introduce some objects to eachother. First we need to tell RedBeanPHP how beans can obtain the toolbox, this means we need to define our own BeanHelper:

Note that we extend the SimpleFacadeBeanHelper here, if you want to implement the interface directly you'll have to add the methods getModelForBean() and getExtractedToolbox() as well.

Now let's do the wiring:

Hybrid

Normally the facade does all this dull work for you. You can also let the facade do this work and still work with instances; simply steal the toolbox from the facade after it has been configured:

Service objects

Many methods in the R-facade are just wrappers around calls to methods on one of these core objects: OODB, Writer and Adapter. However many static methods in R also call so-called service objects. Service objects offer secondary functionality. To instantiate a service object you need to pass the toolbox to its constructor. The toolbox contains everything service object needs to operate: the adapter to connect to the database, the OODB object to call basic ORM methods and the writer to write queries for the database.

For instance, R::find() uses the Finder class. To create an instance of Finder yourself:

That's it. Now we have an instance of the Finder service object. Now to find a bean use:

API

This manual focuses on the facade. For details on individual objects, please consult the API pages.

Read more about the internals of RedBeanPHP.

UUIDs

RedBeanPHP has not been designed for use with UUIDs or GUIDs. However if you really want, you can tune RedBeanPHP to support this.

Enabling UUID support in MySQL

To enable UUID support in MySQL in fluid and frozen mode you need to provide your own QueryWriter. Here is an example of a QueryWriter that enables UUIDs in MySQL:

Now you need to rewire the objects to swap the old Query Writer for the new one:

Depending on the namespaces and aliases you use you might have to adjust this code accordingly.

Enabling UUID support in PostgreSQL

To install the UUID module for PostgreSQL run the following query:

This command requires at least PostgreSQL version 9.1, for earlier versions of Postgres please consult their documentation.

Here is an example class for PostgreSQL: