WordPress.org

Ready to get started?Download WordPress

Plugin Directory

!This plugin hasn't been updated in over 2 years. It may no longer be maintained or supported and may have compatibility issues when used with more recent versions of WordPress.

PostTypeBuilder

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

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":

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":

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):

namespace MyEntities;
use \PostTypeBuilder\Entity;

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

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

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:

namespace MyEntities;
use \PostTypeBuilder\Entity;

/** @Options({publicly_queryable = true}) */
class Book extends Entity{
}

The following example enables publicly queryable and post archives:

namespace MyEntities;
use \PostTypeBuilder\Entity;

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

The following example enables support for text editor and comments:

namespace MyEntities;
use \PostTypeBuilder\Entity;

/** @Options({
    supports = {"title","editor","thumbnail","comments"}
}) */
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:

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:

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:

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:

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:

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.

/** @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:

$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:

$entity = ...

$book_id = $entity->favorite_book_id;

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

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

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

$entity = ...

$books = $entity->favorite_books;

To only get the IDs, use the following code:

$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:

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:

$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:

$query_object = Book::find(5);
$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
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:

$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:

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

Where

The syntax is as following:

$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:

$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):

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:

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:

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:

$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:

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.

Requires: 3.0 or higher
Compatible up to: 3.3.2
Last Updated: 2012-1-23
Downloads: 511

Ratings

3 stars
3.7 out of 5 stars

Support

Got something to say? Need help?

Compatibility

+
=
Not enough data

0 people say it works.
0 people say it's broken.

0,1,0
100,1,1