PostTypeBuilder

Contributors: bornemix
Tags: orm, posttypebuilder, bornemix, database, class
Requires at least: 3.0
Tested up to: 3.3.1
Stable tag: 0.5
License: GPL2

Maps @annotated PHP classes to custom post types, automatically adds relevant fields to the Admin GUI, and LINQ/ActiveRecord-like queries.

Description

PostTypeBuilder is an Object Relational Mapper connecting directly into the Wordpress engine, and provides handy scaffolding through the Wordpress GUI, as well as data querying similar to LINQ and ActiveRecord (Book::find()->where(...)).

<?php
class Book extends Entity{
    /** @Property */
    public $number_of_pages;
}

<?php
while(have_posts()){
	the_post(); $book = new Book($post);
	
	echo "<dt>" . $book->post_title . "</dt>";
	echo "<dd>" . $book->number_of_pages . "</dd>";
}

Included is the Addendum library to support @annotations.

This plugin saves no information on your system (no database tables, no temporary files). All information is supplied by you in your class files.

See Other notes for more info

Register classes

Any classes in wp-content/classes, where the filename (like class_name.php) corresponds to the classname (like ClassName), will be registered as a Wordpress Custom Post Type.

Following example needs to be defined in wp-content/classes/book.php, and results in a registered post type being shown in the admin UI (but not publicly queryable):

<?php
namespace MyEntities;
use \PostTypeBuilder\Entity;

class Book extends Entity{
}

See Other notes for more info

Define properties

Any class properties prefixed by the annotational comment /** @Property */ will be registered as Wordpress metadata, and form fields will appear in the edit/create screen of the post type corresponding to the property type.

Following example, building on the previous Book example class, will display a text form field in the edit/create post screen:

<?php
namespace MyEntities;
use \PostTypeBuilder\Entity;

class Book extends Entity{
	/** @Property */
	public $number_of_pages;
}

To enable the property to carry multiple values, use the = array() assignment:

<?php
/** @Property */
public $authors = array();

See Other notes for more info

Find entities

You can load entities in three ways.

(1) By post ID:

<?php
$book = new Book(21);

(2) By post object (useful in the loop):

<?php
global $post;

$book = new Book($post);

(3) By query:

<?php
$books = Book::find()->where("pages > (NUMERIC)", 10);

foreach($books as $book){ ... }

(Note that the query is executed lazily - ie. at the foreach statement)

Following code shows how to manipulate your entities:

<?php
$book = new Book();
$book->post_title = "Foo";
$book->save();

(Both post_object members and class properties are accessed in a unified way, but class properties have precedence)

See Other notes for more info

Extend the functionality

The plugin is designed to be extensible, so you can override form field generation for your classes, text representations (by overriding __toString), add your own property types, their form field generation, their text representation, you can hook into save events (and more...).

Screenshots

###1. Automatic form field generation of first and second example (in the description tab)###

Register classes

At Wordpress initialization stage, when an HTTP request is made, PostTypeBuilder searches wp-content/classes for PHP files.

Each file is then included, and PostTypeBuilder determines if class \MyEntities\α was defined as a result of that inclusion. MyEntities is the required namespace where you need to define your entities, and α is the filename converted to CamelCase.

For example, if file wp-content/classes/newsletter_issue.php exists, PostTypeBuilder will include that and then check if the class \MyEntities\NewsletterIssue exists.

To change the default namespace, define POSTTYPEBUILDER_ENTITIES_NAMESPACE before PostTypeBuilder gets ahold of it.

Options

There are a number of options available (defined in annotations.php):

• @CanonicalName("")
• @Name("")
• @PluralName("")
• @Labels({})
• @Options({})
• @Panels({})

To use these, include those you want in a single /** */ annotational "DocBlock" comment, with each annotation separated by some whitespace (preferrably, each on a separate line).

@CanonicalName("") defines that the wordpress-internal name should equal the string that is supplied between the parenthesis. By default, this will be equal to the PHP filename, excluding the .php extension. (ie. "book")

The following example registers a Post class, with the internal, canonical name "content_post":

<?php
namespace MyEntities;
use \PostTypeBuilder\Entity;

/** @CanonicalName("content_post") */
class Post extends Entity{
}

@Name("") defines the singular name (used in labels, menus) to be the string supplied between the parenthesis. By default, this will be equal to the CamelCase version of the canonical name, each Camel segment being separated by space. (ie. "Book")

@PluralName("") defines the plural name (used in labels, menus) to be the string supplied between the parenthesis. By default, this will be equal to the implicit (or explicit) singular name + "s". (ie. "Books")

The following example defines the irregular plural name "Virii" for the class "Virus":

<?php
namespace MyEntities;
use \PostTypeBuilder\Entity;

/** @PluralName("Virii") */
class Virus extends Entity{
}

@Labels({}) is a way to override the PostTypeBuilder label determination mechanism, which is partly described above (see generate_class_meta in posttypebuilder.php). Supplied values will override the values provided by PostTypeBuilder. Possible keys correspond to the keys in the labels object documented in register_post_type().

The following example overrides the menu name (subsequent label assignations need to separated by comma):

<?php
namespace MyEntities;
use \PostTypeBuilder\Entity;

/** @Labels({menu_name = "Foo"}) */
class Book extends Entity{
}

@Supports({}) is a way to specify the post type supports array.

Since post types do not work without a title, it is automatically added to whatever you supply here. Editor is not enabled by default.

Possible values are:

• 'title'
• 'editor' (content)
• 'author'
• 'thumbnail' (featured image, current theme must also support post-thumbnails)
• 'excerpt'
• 'trackbacks'
• 'custom-fields'
• 'comments' (also will see comment count balloon on edit screen)
• 'revisions' (will store revisions)
• 'page-attributes' (menu order, hierarchical must be true to show Parent option)
• 'post-formats' add post formats, see Post Formats.

The following example enables support for text editor and comments:

<?php
namespace MyEntities;
use \PostTypeBuilder\Entity;

/** @Supports({"editor","comments"}) */
class Book extends Entity{
}

@IsPublic({}) makes the post type publicly queryable.

By default, entity types are not enabled to be visible to outside users. As such, you will get a 404 error when clicking "View post".

The following example enables "publicly queryable" for the entity type:

<?php
namespace MyEntities;
use \PostTypeBuilder\Entity;

/** @IsPublic */
class Book extends Entity{
}

@Options({}) is a way to override the option defaults that are passed to WP's register_post_type().

The following example enables post archives:

<?php
namespace MyEntities;
use \PostTypeBuilder\Entity;

/**
@IsPublic
@Options({
	has_archive = "books"
})
*/
class Book extends Entity{
}

@Panels specifies the form field groups ("panels") that are to be shown on the edit/create post screen. By default, only one panel is available ("properties"). Supplying @Panels will clear the default panel, so you need to redeclare it if you use this annotation.

The following code specifies that two panels, "Properties" (in main column) and "Options" (in side column) should be used:

<?php
namespace MyEntities;
use \PostTypeBuilder\Entity;

/**
@Panels({
	{
		id="properties",
		label="Properties",
		position="normal"
	},
	{
		id="options",
		label="Options",
		position="side"
	}
})
*/
class Book extends Entity{
	/** @Property(panel="properties") */
	public $author_name;
	/** @Property(type="Boolean",panel="options") */
	public $show_on_startpage;
}

Define properties

Each property that PostTypeBuilder is to be aware of, needs to be prefixed with the annotational comment /** @Property */. Otherwise it will be a plain old PHP class property (not managed by PostTypeBuilder).

By default, the property type is "Text", which can be declared explicitly by including /** @Property(type="Text") */.

The following example defines a property called number_of_pages in the entity Book:

<?php
namespace MyEntities;
use \PostTypeBuilder\Entity;

class Book extends Entity{
	/** @Property */
	public $number_of_pages;
}

Note: The specific visibility public is not required - but without any modifier, the variable name will not be registered as a class property. Either of public, private or protected will do (var evaluates to public), but note that only public properties will show up in the edit/create post screen.

By prefixing the property declaration with the @Property annotation, PostTypeBuilder will:

1. Sync it when relevant instances are loaded/saved from the database.
2. Generate a form field for it when showing the edit/create post screen.
3. Make it available for searching/filtering/ordering when using the PostTypeBuilder query mechanism.

Multiple values

A property can hold multiple values if declared with = array() in the class definition. Form field will then be preceded by a checkbox-list of current values that can be rearranged by drag and drop, and unchecked to be removed. Adding input to form field will add a new value.

Since 0.4, PostTypeBuilder uses WP's post_meta functions which takes care of array serialization when saving.

The following example enables the "author_names" property to hold multiple values:

<?php
namespace MyEntities;
use \PostTypeBuilder\Entity;

class Book extends Entity{
	/** @Property */
	public $author_names = array();
}

Options

To supply options to this annotation, include them in a comma-separated list of equals-separated name-value pairs, the list surrounded by braces between the optional parenthesis after the annotation keyword: /** Property({option1="Foo", option2="Bar"}) */

There are a few options you can supply to this annotation:

• type (default "Text")
• label (default null)
• required (default false)
• panel (default "properties")
• visible (default true)

type specifies the class property type, either a built-in PostTypeBuilder type, an entity declared in MyEntities, or a custom type supplied by you (look in types.php for inspiration).

PostTypeBuilder supplies a number of built-in types:

• Text (default) - Long string.
• LongText - Long string, but the form field will be a multiline <textarea> as opposed to Text.
• Boolean - True/false. Form field will be a checkbox. Saved value will be (string) "true" for true, or null for false.
• GenericPost - Link to a post ID without specifying type. Form field will be a text input field. Saved value will be post ID.
• Image - Link to an attachment image. Form field will be a rudimentary image chooser. Saved value will be attachment ID.
• User - Link to a user in the Wordpress database. Form field will be a <select> dropdown box. Saved value will be user ID.
• Enum - Long string. Form field will be a <select> dropdown box. Saved value will be the value part (not the label part) of the selected enum-options item.

The following example defines a Book which contains a collection of Users who "liked" it:

<?php
namespace MyEntities;
use \PostTypeBuilder\Entity;

class Book extends Entity{
	/** @Property({type="User"}) */
	public $users_who_liked_this_book = array();
}

Enum is kind of special, because it requires another parameter to be specified (enum_options). It is a comma-separated list of equals-separated value-label pairs, enclosed by curly braces, like: {value_one="Label 1",value_two="Label 2"}

The following example defines a Book which contains a property specifying the difficulty of the books' language:

<?php
namespace MyEntities;
use \PostTypeBuilder\Entity;

class Book extends Entity{
	/** @Property({type="Enum",enum_options={easy="Easy",medium="Medium",hard="Hard"}}) */
	public $users_who_liked_this_book = array();
}

It is also possible to define an entity as your property type. This part is kind of special.

If you have an entity class called "Book", then you can make the property link to it by specifying "Book" as its type.

You need to name your property with an ending "_id". For properties with multiple values, it must end with _ids.

<?php
/** @Property(type="Book") */
public $favorite_book_id;

Now, when accessing your entity object, you can get its associated object by accessing the property name without id:

<?php
$entity = ...

$book = $entity->favorite_book;

The preceding code will give you the whole Entity object, loaded with properties and all. To get just the id, use the proper property name:

<?php
$entity = ...

$book_id = $entity->favorite_book_id;

When having properties with multiple values, name your code with the singular name + "_ids":

<?php
/** @Property(type="Book") */
public $favorite_book_ids;

PostTypeBuilder listens for the property name minus "_ids" plus "s", like the following code:

<?php
$entity = ...

$books = $entity->favorite_books;

To only get the IDs, use the following code:

<?php
$entity = ...

$book_ids = $entity->favorite_book_ids;

Note: To change the collection, you need to manipulate the IDs array, not the lazily loaded proxy properties.

label specifies the text used for labelling the form field on the edit/create post screen. Currently, PostTypeBuilder does not support i18n for any of its interface functionality.

The following example specifies the label for two properties:

<?php
namespace MyEntities;
use \PostTypeBuilder\Entity;

class Book extends Entity{
	/** @Property(label="Number of pages (do not use this one!)") */
	public $pages;
	/** @Property(type="Image", label="Image of first page") */
	public $first_page_image;
}

required specifies that the property must not be empty. Currently, the only thing happening when this option is set to true, a red star comes up next to the label. No validation of any kind is made.

panel specifies which panel should contain the form field on the edit/create post screen. Look for the Panels section below.

visible specifies wether the form field should be shown on screen or not. If not, the only way to interact with the property is through code.

Find entities

This section is not done!

To start using the query mechanism, you will need to retrieve a Query object. This is done like so:

<?php
$query_object = Book::find();

This object can then be used to add parameters to what will add up to an WP Query object, which will be executed when accessed.

To limit the amount of hits in your query to 5, use the following code:

<?php
$query_object = Book::find(5);

<?php
$first_item = $query_object[0]; // executes search and returns first match
$second_item = $query_object[1]; // by now, result is already cached in $query_object, and another query will not be done

<?php
foreach($query_object as $item){ // executes search and returns iterator
	...
}

When having executed the search query, changes to the query object will have no effect.

When making the query, the query acts as a proxy for its found instances. Even things like $book_title = Book::find()->where("author_name", "Björn Ali Göransson")->post_title will work. To get the real entity object, use get($index = 0) or array notation [$index].

The following example does a search for book author name:

<?php
$query_object = Book::find();
$query_object->where("author_name", "Björn Ali Göransson");
$book = $query_object[0];

Almost each query method returns the query object itself, by the way, which makes way for chaining:

<?php
$book = Book::find()->where("author_name", "Björn Ali Göransson")->get(0);

Where

The syntax is as following:

<?php
$query_object->where(key, value);

To make a search for a property, you use the same syntax. When searching for properties, though, you have more options.

The following example searches for books where year is between 1950 and 2000:

<?php
$query_object = Book::find();

$query_object->where("year > (NUMERIC)", 1950);

$query_object->where("year < (NUMERIC)", 2000);

The first parameter can be either name, name operator or name operator (format).

name should be a valid PostTypeBuilder property.

Operator should be one of the following:

• =
• !=
• >
• >=
• <
• <=
• LIKE
• NOT LIKE
• IN
• NOT IN
• BETWEEN
• NOT BETWEEN

If you don't specify an operator, then like WP_Query, it will default to =.

format specifies to which data type the value should be casted.

Possible values are:

• NUMERIC
• BINARY
• CHAR
• DATE
• DATETIME
• DECIMAL
• SIGNED
• TIME
• UNSIGNED.

If you don't specify a format, then like WP_Query, it will default to CHAR.

Extend default functionality

Custom form fields

To get custom form fields for a type, extend the type in your own file (maybe functions.php in your theme?) and implement your own generate_input_field method. See types.php for inspiration.

In order to implement custom form fields for choosing an entity, override the generate_input_field in your entity class.

The following example overrides the <select> dropdown form field for selecting Books, as it would be too long to load such a list, and instead delegates the generate_input_field to the Text type (and thereby exposing the ID):

<?php
namespace MyEntities;
use \PostTypeBuilder\Entity;

class Book extends Entity{
	public function generate_input_field($name_and_id, $value = null, $property = null, $property_annotation = null, $many = false){
		\Addendum\TextPropertyType::generate_input_field($name_and_id, $value, $property, $property_annotation, $many);
	}
}

See entity.class.php and types.php for inspiration on how to implement this method.

Text representation of entities

When listing entities for form fields, the text representation of the entity is used to represent it. It defaults to the post title, but if that doesn't exist, it shows other things (see entity.class.php). This functionality can be changed by overriding the __toString() method.

The following example shows the authors in the books' text representation:

<?php
namespace MyEntities;
use \PostTypeBuilder\Entity;

class Book extends Entity{
	/** @Property */
	public $author_names = array();
	
	public function __toString(){
		return $this->post_title . " by " . implode(", ", $this->author_names);
	}
}

Class methods

Class methods can be added without any "plumbing".

The following example adds a "sort" method to the Book class:

<?php
namespace MyEntities;
use \PostTypeBuilder\Entity;

class Book extends Entity{
	/** @Property */
	public $author_names;
	
	public function sort_names(){
		sort($this->author_names);
	}
}

The method can then be used like the following code:

<?php
$book = ...

$book->sort();

$book->save();

Event hooks

You may "hook on" certain post events by defining corresponding class methods. They need to be static, as an entity instance isn't always desirable in these events. All methods receive the associated post object as argument.

Following is a list of all methods that can be implemented:

• clean_post_cache - Runs when post cache is cleaned.
• delete_post - Runs when a post or page is about to be deleted.
• edit_post - Runs when a post or page is updated/edited, including when a comment is added or updated (which causes the comment count for the post to update).
• save_post - Runs whenever a post or page is created or updated, which could be from an import, post/page edit form, xmlrpc, or post by email.
• publish_post - Runs when a post is published, or if it is edited and its status is "published".
• pending_post - Same as publish_post but with status "pending".
• draft_post - Same as publish_post but with status "draft".
• auto_post - Same as publish_post but with status "auto".
• future_post - Same as publish_post but with status "future".
• private_post - Same as publish_post but with status "private".
• inherit_post - Same as publish_post but with status "inherit".
• trash_post - Same as publish_post but with status "trash".

The following example sorts author names on save:

<?php
namespace MyEntities;
use \PostTypeBuilder\Entity;

class Book extends Entity{
	/** @Property */
	public $author_names;
	
	public function sort_names(){
		sort($this->author_names);
	}
	
	static function save_post($post_object){
		$book = new Book($post_object);
		
		$book->sort_names();
		
		$book->save();
	}
}

Note: The save_post will not fire recursively into itself, which means that the last call to $book->save() will not make the save_post() execute again.