API Documentation
\
Charcoal
Loader
Model
Service
ServiceProvider
Source
Database
Validator

\Charcoal\SourceDatabaseSource

Database Source, through PDO.

Summary

Methods
Properties
Constants
__construct()
reset()
setData()
setModel()
model()
hasModel()
setProperties()
properties()
addProperty()
setFilters()
filters()
addFilter()
setOrders()
orders()
addOrder()
setPagination()
pagination()
setPage()
page()
setNumPerPage()
numPerPage()
createConfig()
loadItem()
loadItems()
saveItem()
updateItem()
deleteItem()
setTable()
table()
createTable()
alterTable()
tableExists()
tableStructure()
tableIsEmpty()
db()
loadItemFromKey()
loadItemFromQuery()
loadItemsFromQuery()
dbQuery()
sqlLoad()
sqlLoadCount()
sqlSelect()
sqlFilters()
sqlOrders()
sqlPagination()
No public properties found
DEFAULT_DB_HOSTNAME
DEFAULT_DB_TYPE
createFilter()
createOrder()
createPagination()
getter()
setter()
$filters
$orders
$pagination
N/A
camelize()
pascalize()
getModelFields()
$model
$properties
$pdo
$table
$db
N/A

Constants

DEFAULT_DB_HOSTNAME

DEFAULT_DB_HOSTNAME

DEFAULT_DB_TYPE

DEFAULT_DB_TYPE

Properties

$filters

$filters : array

Array of `Filter` objects

Type

array

$orders

$orders : array

Array of `Order` object

Type

array

$properties

$properties : array

Type

array

$pdo

$pdo : \PDO

Type

\PDO

$table

$table : string

Type

string

$db

$db : array

Type

array

Methods

__construct()

__construct(array  $data) : void

Parameters

array $data

Class dependencies.

setData()

setData(array  $data) : \Charcoal\Source\AbstractSource

Initialize the source's properties with an array of data.

Parameters

array $data

The source data.

Returns

\Charcoal\Source\AbstractSource —

Chainable

model()

model() : \Charcoal\Model\ModelInterface

Return the source's Model.

Throws

\Exception

If not model was previously set.

Returns

\Charcoal\Model\ModelInterface

hasModel()

hasModel() : boolean

Returns

boolean

setProperties()

setProperties(array  $properties) : \Charcoal\Source\ColelectionLoader

Set the properties of the source to fetch.

This method accepts an array of property identifiers (property ident, as string) that will, if supported, be fetched from the source.

If no properties are set, it is assumed that all the Model's properties are to be fetched.

Parameters

array $properties

The properties.

Returns

\Charcoal\Source\ColelectionLoader —

Chainable

properties()

properties() : array

Returns

array

addProperty()

addProperty(string  $property) : \Charcoal\Source\CollectionLoader

Parameters

string $property

Property ident.

Throws

\InvalidArgumentException

If property is not a string or empty.

Returns

\Charcoal\Source\CollectionLoader —

Chainable

setFilters()

setFilters(array  $filters) : \Charcoal\Source\Collection

Parameters

array $filters

The filters to set.

Returns

\Charcoal\Source\Collection —

Chainable

filters()

filters() : array

Returns

array

addFilter()

addFilter(string|array|\Charcoal\Source\Filter  $param, mixed  $val = null, array  $options = null) : \Charcoal\Source\CollectionLoader

Add a collection filter to the loader.

There are 3 different ways of adding a filter:

  • as a Filter object, in which case it will be added directly.
    • addFilter($obj);
  • as an array of options, which will be used to build the Filter object
    • addFilter(['property' => 'foo', 'val' => 42, 'operator' => '<=']);
  • as 3 parameters: property, val and options
    • addFilter('foo', 42, ['operator' => '<=']);

Parameters

string|array|\Charcoal\Source\Filter $param

The filter property, or a Filter object / array.
mixed $val

Optional: Only used if the first argument is a string.
array $options

Optional: Only used if the first argument is a string.

Throws

\InvalidArgumentException

If property is not a string or empty.

Returns

\Charcoal\Source\CollectionLoader —

(Chainable)

setOrders()

setOrders(array  $orders) : \Charcoal\Source\CollectionLoader

Parameters

array $orders

The orders to set.

Returns

\Charcoal\Source\CollectionLoader —

Chainable

orders()

orders() : array

Returns

array

addOrder()

addOrder(string|array|\Charcoal\Source\Order  $param, string  $mode = 'asc', array  $orderOptions = null) : \Charcoal\Source\CollectionLoader

Parameters

string|array|\Charcoal\Source\Order $param

The order property, or an Order object / array.
string $mode

Optional.
array $orderOptions

Optional.

Throws

\InvalidArgumentException

If the param argument is invalid.

Returns

\Charcoal\Source\CollectionLoader —

Chainable

setPagination()

setPagination(mixed  $param) : \Charcoal\Source\CollectionLoader

Parameters

mixed $param

The pagination object or array.

Throws

\InvalidArgumentException

If the argument is not an object or array.

Returns

\Charcoal\Source\CollectionLoader —

Chainable

pagination()

pagination() : \Charcoal\Source\Pagination

Get the pagination object.

If the pagination wasn't set previously, a new (default / blank) Pagination object will be created. (Always return a PaginationInterface object)

Returns

\Charcoal\Source\Pagination

setPage()

setPage(integer  $page) : \Charcoal\Source\CollectionLoader

Parameters

integer $page

The page number.

Throws

\InvalidArgumentException

If the page argument is not numeric.

Returns

\Charcoal\Source\CollectionLoader —

Chainable

page()

page() : integer

Returns

integer

setNumPerPage()

setNumPerPage(integer  $num) : \Charcoal\Source\CollectionLoader

Parameters

integer $num

The number of items to retrieve per page.

Throws

\InvalidArgumentException

If the num per page argument is not numeric.

Returns

\Charcoal\Source\CollectionLoader —

Chainable

numPerPage()

numPerPage() : integer

Returns

integer

createConfig()

createConfig(array  $data = null) : \Charcoal\Source\DatabaseSourceConfig

ConfigurableTrait > createConfig()

Overrides the method defined in AbstractSource to returns a DatabaseSourceConfig object.

Parameters

array $data

Optional.

Returns

\Charcoal\Source\DatabaseSourceConfig

loadItems()

loadItems(\Charcoal\Source\StorableInterface|null  $item = null) : array

Parameters

\Charcoal\Source\StorableInterface|null $item

Optional item to use as model.

Returns

array

saveItem()

saveItem(\Charcoal\Source\StorableInterface  $item) : mixed

Save an item (create a new row) in storage.

Parameters

\Charcoal\Source\StorableInterface $item

The object to save.

Throws

\Exception

If a database error occurs.

Returns

mixed —

The created item ID, or false in case of an error.

updateItem()

updateItem(\Charcoal\Source\StorableInterface  $item, array  $properties = null) : boolean

Update an item in storage.

Parameters

\Charcoal\Source\StorableInterface $item

The object to update.
array $properties

The list of properties to update, if not all.

Returns

boolean —

Success / Failure

deleteItem()

deleteItem(\Charcoal\Source\StorableInterface  $item = null) : boolean

Delete an item from storage

Parameters

\Charcoal\Source\StorableInterface $item

Optional item to delete. If none, the current model object will be used.

Throws

\Exception

If the item does not have an ID.

Returns

boolean —

Success / Failure

setTable()

setTable(string  $table) : \Charcoal\Source\DatabaseSource

Set the database's table to use.

Parameters

string $table

The source table.

Throws

\InvalidArgumentException

If argument is not a string or alphanumeric/underscore.

Returns

\Charcoal\Source\DatabaseSource —

Chainable

table()

table() : string

Get the database's current table.

Throws

\Exception

If the table was not set.

Returns

string

createTable()

createTable() : boolean

Create a table from a model's metadata.

Returns

boolean —

Success / Failure

alterTable()

alterTable() : boolean

Alter an existing table to match the model's metadata.

Returns

boolean —

Success / Failure

tableExists()

tableExists() : boolean

Returns

boolean

tableStructure()

tableStructure() : array

Get the table columns information.

Returns

array

tableIsEmpty()

tableIsEmpty() : boolean

Check wether the source table is empty (`true`) or not (`false`)

Returns

boolean

db()

db() : \PDO

Throws

\Exception

If the database can not set.

Returns

\PDO

loadItemFromKey()

loadItemFromKey(string  $key, mixed  $ident, \Charcoal\Source\StorableInterface|null  $item = null) : \Charcoal\Source\StorableInterface

Load item from a custom column's name ($key)

Parameters

string $key

Column name.
mixed $ident

Value of said column.
\Charcoal\Source\StorableInterface|null $item

Optional. Item (storable object) to load into.

Throws

\Exception

If the query fails.

Returns

\Charcoal\Source\StorableInterface —

Item

loadItemFromQuery()

loadItemFromQuery(string  $query, array  $binds = array(), \Charcoal\Source\StorableInterface  $item = null) : \Charcoal\Source\StorableInterface

Parameters

string $query

The SQL query.
array $binds

Optional. The query parameters.
\Charcoal\Source\StorableInterface $item

Optional. Item (storable object) to load into.

Throws

\Exception

If there is a query error.

Returns

\Charcoal\Source\StorableInterface —

Item.

loadItemsFromQuery()

loadItemsFromQuery(string  $q, array  $binds = array(), \Charcoal\Source\StorableInterface|null  $item = null) : array

Loads items to a list from a query Allows external use.

Parameters

string $q

The actual query.
array $binds

This has to be done.
\Charcoal\Source\StorableInterface|null $item

Model Item.

Returns

array —

Collection of Items | Model

dbQuery()

dbQuery(string  $q, array  $binds = array(), array  $binds_types = array()) : \Charcoal\Source\PDOStatement|false

Execute a SQL query, with PDO, and returns the PDOStatement.

If the query fails, this method will return false.

Parameters

string $q

The SQL query to executed.
array $binds

Optional. Query parameter binds.
array $binds_types

Optional. Types of parameter bindings.

Returns

\Charcoal\Source\PDOStatement|false —

The PDOStatement, or false in case of error

sqlLoad()

sqlLoad() : string

Throws

\Exception

If the source does not have a table defined.

Returns

string

sqlLoadCount()

sqlLoadCount() : string

Get a special SQL query for loading the count.

Throws

\Exception

If the source does not have a table defined.

Returns

string

sqlSelect()

sqlSelect() : string

Returns

string

sqlFilters()

sqlFilters() : string

Returns

string

sqlOrders()

sqlOrders() : string

Returns

string

sqlPagination()

sqlPagination() : string

Returns

string

getter()

getter(string  $key, string  $case = 'camel') : string

Allow an object to define how the key getter are called.

Parameters

string $key

The key to get the getter from.
string $case

Optional. The type of case to return. camel, pascal or snake.

Returns

string —

The getter method name, for a given key.

setter()

setter(string  $key, string  $case = 'camel') : string

Allow an object to define how the key setter are called.

Parameters

string $key

The key to get the setter from.
string $case

Optional. The type of case to return. camel, pascal or snake.

Returns

string —

The setter method name, for a given key.

camelize()

camelize(string  $str) : string

Transform a snake_case string to camelCase.

Parameters

string $str

The snake_case string to camelize.

Returns

string —

The camelCase string.

pascalize()

pascalize(string  $str) : string

Transform a snake_case string to PamelCase.

Parameters

string $str

The snake_case string to pascalize.

Returns

string —

The PamelCase string.

getModelFields()

getModelFields(\Charcoal\Model\ModelInterface  $model, array|null  $properties = null) : array

Get all the fields of a model.

Parameters

\Charcoal\Model\ModelInterface $model

The model to get fields from.
array|null $properties

Optional list of properties to get. If null, retrieve all (from metadata).

Returns

array