RedBeanPHP 4
The Power ORM


Welcome to RedBeanPHP 4.0, the new version of RedBeanPHP ORM. RedBeanPHP has been released on: 2014-04-01. RedBeanPHP 4.0 takes our little yet powerful ORM to the next level. This page discusses the general idea behind RedBeanPHP 4.0 and details the new features.


I am very happy to announce the official release of RedBeanPHP 4.0, a brand new version of our ORM library. After 9 betas and 1.5 month of pro-active testing we are ready to deliver a robust and solid, future proof RedBeanPHP package. Some stats: 13177 unit tests (core only), 100% code coverage, only 2534 lines of 'effective' code (big clean up).

New in RedBeanPHP 4

RedBeanPHP 4 KS is a new version of the RedBeanPHP ORM library. The fourth version of RedBeanPHP is 'how I would have written RedBeanPHP' if I started right now instead of five years ago when the RedBeanPHP project started. I have removed lots of features. Some of them will reappear in plugins, others will not. The core of RedBeanPHP has been stripped of all experiments and legacy cruft build up over the years. RedBeanPHP 4 KS has a very clean, maintainable core incorporating many new concepts of the new PHP language: namespaces and phar. Some concepts have been simplified to be more in line with the 'on-the-fly' philosophy of RedBeanPHP, for instance, dependencies (to remove beans and add foreign keys) are no longer specified 'a priori', instead you add them on-the-fly by accessing the x-own-list. This new incarnation of RedBeanPHP should pave the way for future development of the library.


This is a list of new features in vesion 4.0 of RedBeanPHP.


RedBeanPHP 4.0 is the first version to support native PHP namespaces, thus requiring PHP 5.3 or higher. While the code of RB has been namespaced properly, the R class is still available without a namespace, this has been done to avoid having to use the obnoxious 'use' statements all over the place. The R facade class and some other classes are loaded into global namespace by the phar-loader. This means that for most people nothing actually changes regarding the use of RedBeanPHP.

Phar distribution

RedBeanPHP was always about avoiding auto-loaders and configuring include paths. Therefore we always put the whole thing into one file. In a sense we were ahead of our time because this is of course exactly what the PHP PHAR functionality does. Phar allows us to support PHP namespaces while preserving the advantage of compiling everything into a single file for ease of use and ease of distribution.

Some IDEs have rather limited support for PHAR files. This is why we ship an ide-support.php file for your IDE containing the most important method definitions. Just keep this file around for your IDE to scan but do not include it. It should fix any autocomplete issues while IDE vendors are working to improve PHAR integration. Yes, I am looking at you NetBeans, Eclipse!

Big clean up

RedBeanPHP 4 is 'RedBeanPHP' as I would have written it today, instead of in 2009. This version is a major version and therefore it is not backward compatible. I took the liberty to remove all cruft accumulated over the years making the library slim and more maintainable. This new manual website covers only functionality found in version 4, the old version 3 manual will remain available and covers the other topics. Among things that have been removed are: Cooker (plugin and partially implemented in dispense), BeanCan Servers (now plugins), certain Query Writers (now plugins), Dependency Injectors (probably moves to RedBeanPHP Adaptive), old Association API and the Bean Cache.

CUBRID now a plugin

CUBRID Query Writer has been moved to the plugin repository. Instead of bundling all Query Writers in the core we will try to improve the plugin infrastructure for writers using additional (test)-hooks. This will help to keep the core slim and maintainable.

Exclusive own-list

The Exclusive own-list is a new feature in RedBeanPHP 4.0. This list replaces the R::dependencies method managing foreign keys. In short accessing an own-list with the x-prefix will cause the adding of a foreign key constraint with cascading deletes (only if used for the first time) and it will tell RedBeanPHP to trash all the beans in the list if the list gets emptied (breaking the association). Thus we 'translate' the concept of dependencies to the 'on-the-fly' principles of RedBeanPHP as it should be.


While RedBeanPHP manuals always warned against using plural bean type names (books) people did not like the resulting list names: ownPage, ownBook etc. Therefore instead of using ownPage you may now also open a list using: ownPageList. This also applies to shared lists.


The Traverse function is a new feature in RedBeanPHP 4.0. This method replaces the searchIn() method for searching trees.

Other features

Besides the big features mentioned above, there are also a lot of minor improvements. Here is a quick and incomplete list:

  • 10% performance improvement for basic CRUD operations
  • Performance improvements for bean conversion
  • Improved Array Access interface (you can now use arrays instead of beans all the time)
  • Improved handling of unique constraints
  • Added EID() function to easily insert ENUM bean IDs in queries
  • Constraints now also use ON UPDATE CASCADE
  • Dispense works more consistently now
  • Fixed an issue with type of return ID value in Postgres driver
  • Fixed possible cache collision issue
  • Performance improvements for fluid mode


As it turns out some people see RedBeanPHP more as a begin of something else. While RedBeanPHP 4 KS returns to the roots of RedBeanPHP, simplifying the entire library, the Adaptive branch will follow its own unique development path. Complex utilities like dependency injectors, query builders and pipelines will probably become available in the new RedBeanPHP Adaptive branch. So, for industrial strength RedBeanPHP visit our Adaptive friends !

Version 4 FAQ

This is a list of questions and answers regarding the 4.0 release.

What about PHP 5.3 - PHP 5.3.3 ?

These versions of PHP lack some important 5.3 features, however there is a special version in the download archive that supports these versions go to the archive and download RedBeanPHP 4 Beta 9b (same as FINAL 4.0 but with additional patch).

Why has the Preloader been removed?

When I wrote the preloader, the original purpose was to prevent for-each loops to fire queries when retrieving the parent of a bean. Later I added the writer cache which could take care of this but was turned off by default. In RedBeanPHP the writer cache is turned on by default solving the original problem. Meanwhile people requested all kinds of new features for the Preloader like support for loading own-lists, shared-lists and even aliases and SQL snippets. It even got its own syntax. I decided to remove the preloader because I believe simple SQL is better suited to query large amounts of records all at once for overviews and reports.
This functionality is still available as a plugin.

Why has graph() been removed from core?

R::graph() was a powerful feature to load and updates beans directly from forms. However the graph() function assumed you were also using FUSE for validation. Otherwise the function could lead to serious architectural and security defects. I fixed this in version 3, but then it became less powerful, so in version 4 I decided to remove it entirely from the core.
This functionality is still available as a plugin.
Also note that the new R::dispense() method works much like the old graph() method.

Why is R::associate gone?

The R::associate() method (as well as unassociate etc...) is a relic from the past. In the earliest versions of RedBeanPHP I believed you only needed many-to-many relations. Although this was true, performance became a real bottleneck. I had to find a way to apply the on-the-fly philosophy to N-1 relations as well, this resulted in the introduction of own-lists and shared-lists. Since then, I kept the old associate() method for backward compatibility reasons. In version 4 however I decided to finally clean up.

Why are the BeanCan Servers gone?

They blurred the distinction between plugin and core. Also, the RedBeanPHP Adaptive branch is going more in the direction of a framework which is a better place for BeanCan as well. RedBeanPHP 4 returns to the core of the library: on-the-fly ORM. Another reason is that it turns out it is pretty much impossible to prescribe the interface of a JSON or REST API.
This functionality is still available as a plugin

Why does RedBeanPHP 4KS not support composer?

As of version 4 KS I revoke all support for Composer. There are several reasons for this:

  • I don't want newcomers to learn about Composer first. The PHAR distribution is easy to use and does not require any prior knowledge about other systems
  • I question the usefulness of systems like Composer/Gems/NPM - I think this should be handled manually
  • Supporting Composer well, requires me to change the layout of my library (putting everything in a lib folder) which is ridiculous
  • I don't want to make RedBeanPHP depending on Composer. Many libraries I use are completely messed up because their authors assume everyone is using Composer
  • Packagist uses Github as a distribution tool - which is a mistake. Git is version control system and not meant to be used for this.

New in RedBeanPHP 3.5.7

This is a minor maintenance update.

  • Fixed issue in QueryWriter cache (3.5.7b)
  • Improved stacktrace in SQL exception
  • Improved performance of convertToBeans() method
  • Allow duplication of trees
  • With now also works with joins


RedBeanPHP Easy ORM for PHP © 2014 () and the RedBeanPHP community () - Licensed New BSD/GPLv2 - RedBeanPHP Archives