Download the PHP package rsanchez/deep without Composer

Deep

A read-only set of Eloquent models for ExpressionEngine Channel Entries. This library has a few goals in mind:

• replicate as much of the {exp:channel:entries} functionality as possible using Eloquent query scopes
• chainable with standard Eloquent model methods (ex. ->where('foo', 'bar'))
• minimize the number of queries needed using eager loading
• provide an base plugin from which EE plugins/modules can extend, which has near parity with {exp:channel:entries}
• automatically fetch custom fields using field names and entities instead of just raw text from exp_channel_data

For more detailed information, see the auto-generated API docs.

Version Compatibility Chart

Installation

Run this command in your terminal:

composer require rsanchez/deep

Setup

ExpressionEngine

Make sure you load composer's autoloader at the top of your config.php (your actual vendor path may vary):

require_once FCPATH.'vendor/autoload.php'

Then you can create your own plugin that uses Deep by extending the BasePlugin class. Or you can use the built-in wrapper class, which bootstraps Deep with EE for you:

Laravel

Deep comes with a service provider for Laravel. Add this to the list of providers in app/config/app.php:

'rsanchez\Deep\App\Laravel\ServiceProvider',

use rsanchez\Deep\Model\Entry;

route('/blog', function()
{
    $entries = Entry::channel('blog')->get();
    return View::make('blog.index')->withEntries($entries);
});

route('/blog/json', function()
{
    $entries = Entry::channel('blog')->get();
    return Response::json($entries);
});

If you are using a table prefix for your database tables (EE uses exp_ by default, so you most likely are), make sure to set the prefix in Laravel's app/config/database.php

If you need to use a DB connection other than Laravel's default connection, you should add the following configuration to app/config/database.php:

'deep' => array(
    'connection' => 'your_connection_name',
),

The specified connection will be used for all of Deep's models.

Generic PHP (or other framework)

First you must bootstrap Eloquent for use outside of Laravel. There are many guides out there on how to do this.

Then you can simply use the generic wrapper:

Or instantiate your own instance of the Deep DI container if you prefer:

Using the Phar archive for easier distribution

You can build a Phar archive as an alternative installation method. The best way to package Deep with your custom distributed add-on is to use the Phar archive, since EE doesn't natively support compser installation out of the box.

To build the Phar archive, you must have box installed. Then you can clone this repo, run composer install to fetch all the dependencies, and run box build to create the Phar archive. The archive can be found in build/deep.phar after it's built.

Now you can package that single Phar archive with your add-on (say, in a phar folder in your add-on root) and load it like so:

Query Scopes

Filtering Scopes

Filtering scopes should look familiar, since most of them relate to a native {exp:channel:entries} parameter.

Channel Name

Not Channel Name

Channel ID

Not Channel ID

Author ID

Not Author ID

Category ID

Not Category ID

All Categories

Only show entries that have all of the specified categories.

Not All Categories

Exclude entries that have all of the specified categories.

Category Name

Not Category Name

Category Group

Not Category Group

Day

Dynamic Parameters

Entry ID

Not Entry ID

Entry ID From

Entry ID To

Fixed Order

Member Group ID

Not Member Group ID

Limit

Month

Offset

Show Expired

Show Future Entries

Show Pages

Show Pages Only

Site ID

Start On

Unix time:

Or use a DateTime object:

Stop Before

Unix time:

Or use a DateTime object:

Sticky

Status

Not Status

URL Title

Not URL Title

Username

Not Username

Year

Tagparams

This scope accepts an array of parameters And applies all the supported {exp:channel:entries} parameters to the query.

The following channel:entries parameters are not implemented by the tagparams scope:

• cache
• display_by
• disable
• dynamic
• dynamic_start
• month_limit
• paginate
• paginate_base
• paginate_type
• refresh
• related_categories_mode
• relaxed_categories
• require_entry
• show_current_week
• track_views
• week_sort
• uncategorized_entries

Eager Loading Scopes

These scopes force eager loading of certain relationships. Eager loading of custom field data is done automatically with the Entry model (and the Entries proxy). Use the Title model (or the Titles proxy) to not eager load custom field data.

With Categories

Eager load the categories attribute.

With Category Fields

Eager load the categories attribute with custom category fields.

With Author

Eager load the author attribute.

With Author Fields

Eager load the author attribute with custom member fields.

With Parents

Eager load the parents attribute (native EE relationship fields only).

With Siblings

Eager load the siblings attribute (native EE relationship fields only).

With Comments

Eager load the comments attribute, a collection of Comment models.

Without Fields

Do not load custom fields.

Without Child Fields

Do not load custom fields in child (Playa/Relationship) entries.

With Fields

Specify exactly which custom fields to load.

Custom Field Scopes

This set of scopes allows you to use the traditional some Eloquent methods with custom field names instead of field_id_X.

Order By Field

Where Field

Or Where Field

Where Field In

Or Where Field In

Where Field Not In

Or Where Field Not In

Where Field Between

Or Where Field Between

Where Field Not Between

Or Where Field Not Between

Where Field Null

Or Where Field Null

Where Field Not Null

Or Where Field Not Null

Where Field Contains

This is like search:your_custom_field="foo|bar".

Or Where Field Contains

Where Field Does Not Contain

This is like search:your_custom_field="not foo|bar".

Or Where Field Does Not Contain

Where Field Contains Whole Word

This is like search:your_custom_field="foo\W|bar\W".

Or Where Field Contains Whole Word

Where Field Does Not Contain Whole Word

This is like search:your_custom_field="not foo\W|bar\W".

Or Where Field Does Not Contain Whole Word

Advanced Category Querying

This library makes use of Eloquent's relationship capabilities. If you need to do more advanced category querying than the default category scopes, you can use the whereHas and orWhereHas methods.

Entry objects

Each entry object has the following string properties from the exp_channel_titles table.

Dates

Entries have the following date properties. Each of these will be a Carbon object. expiration_date, comment_expiration_date and recent_comment_date can be null.

Dates are serialized to ISO-8601 format during toArray and toJson. To do this, Deep sets Carbon's default format to DateTime::ISO8601 or Y-m-d\TH:i:sO. If you wish to change the default format, you should call \Carbon\Carbon::setToStringFormat($yourDateFormatString) prior to serialization. If you wish to reset this attribute globally in Carbon to the original default, you should call Carbon::resetToStringFormat().

Channel object

If you need info about the entry's channel, there is the $entry->channel object. The channel object contains the following properties from the exp_channels table.

Categories

Each Entry object has a categories property which is a collection of Category objects. Use the withCategories or withCategoryFields scope to eager load this relationship.

Author

Each Entry object has a author property which is a Member object. Use the withAuthor or withAuthorFields scope to eager load this relationship.

Comments

Each Entry object has a comments property which is a collection of Comment objects. Use the withComments scope to eager load this relationship.

Custom Fields

Entries have their custom fields as properties, keyed by the field short name. Most custom field properties merely the string data from the corresponding exp_channel_data field_id_X column.

For the following fieldtypes, an entry's custom field properties will be special objects, rather than string data from the exp_channel_data table.

Matrix & Grid

Matrix & Grid fields will be Eloquent Collections of Row objects. Each Row object has string properties keyed to the column short name from the exp_matrix_data and exp_channel_grid_field_X tables, respectively. Custom Row fields follow the same logic as Entry custom fields.

Playa & Relationship

Playa & Relationship fields will be Eloquent Collections of related Entry objects. These Entry objects behave just as parent Entry objects do.

Assets

Assets fields will be Eloquent Collections of Asset objects. Asset objects have the following properties:

File

File fields will be a single File object. File objects have the following properties:

Date

Date fields will be a single Carbon object.

Multiselect, Checkboxes, Fieldpack Multiselect, Fieldpack Checkboxes & Fieldpack List

These fields will be arrays of values:

Extending the BasePlugin class

The abstract rsanchez\Deep\Plugin\BasePlugin class is provided as a base for ExpressionEngine modules and plugins. The parseEntries method parses a template using an EntryCollection.

Entries

Now you can parse your plugin like a channel:entries tag:

The following channel:entries single tags / conditionals are not implemented by the BasePlugin class:

• gmt_entry_date
• gmt_edit_date
• member_search_path
• relative_url
• relative_date
• trimmed_url
• week_date

The following channel:entries parameters are not implemented by the BasePlugin class:

• display_by
• dynamic_start
• month_limit
• paginate_type
• relaxed_categories
• show_current_week
• track_views
• week_sort
• uncategorized_entries

The parseEntries method has the following default parameters:

orderby="entry_date"
show_future_entries="no"
show_expired="no"
sort="desc"
status="open"
dynamic="yes"
limit="100"

You can change this by overloading the getEntriesDefaultParameters method in your plugin/module class:

protected function getEntriesDefaultParameters()
{
    return array(
        'dynamic' => 'no',
        'status' => 'open|Featured',
    );
}

The BasePlugin class allows the following parameters on Matrix, Grid, Playa and Relationships tag pairs:

• limit
• offset
• orderby
• sort
• search:your_field
• fixed_order
• backspace
• entry_id*
• row_id**

*Playa and Relationships only **Matrix and Grid only

Categories

The BasePlugin class can also parse the equivalent of a channel:categories tag.

Now you can parse your plugin like a channel:categories tag:

{exp:my_plugin:categories channel="blog" style="nested"}
  <a href="{path='blog'}"{if active} class="active"{/if}>{category_name}</a>
{/exp:my_plugin:categories}

{exp:my_plugin:offices country="{segment_2}"}
{if no_results}{redirect="404"}{/if}
<h1><a href="{site_url}offices/{category_url_title}">{category_name}</a></h1>
{category_description}
{/exp:my_plugin:offices}

The parseCategories method has the following default parameters:

show_empty="yes"
show_future_entries="no"
show_expired="no"
restrict_channel="yes"
style="nested"
id="nav_categories"
class="nav_categories"
orderby="categories.group_id|categories.parent_id|categories.cat_order"

You can change this by overloading the getCategoriesDefaultParameters method in your plugin/module class:

protected function getCategoriesDefaultParameters()
{
    $params = parent::getCategoriesDefaultParameters();

    $params['style'] = 'linear';

    return $params;
}