class DataObjectSchema (View source)

Provides dataobject and database schema mapping functionality

Traits

A class that can be instantiated or replaced via DI

Provides extensions to this object to integrate it with standard config API methods.

Constants

HAS_ONE_MULTI_RELATIONAL

Configuration key for has_one relations that can support multiple reciprocal has_many relations.

DB_ONLY

fieldSpec should exclude virtual fields (such as composite fields), and only include fields with a db column.

UNINHERITED

fieldSpec should only return fields that belong to this table, and not any ancestors

INCLUDE_CLASS

fieldSpec should prefix all field specifications with the class name in RecordClass.Column(spec) format.

Config options

table_namespace_separator string

Default separate for table namespaces. Can be set to any string for databases that do not support some characters.

Properties

protected array $databaseFields

Cache of database fields

protected array $databaseIndexes

Cache of database indexes

protected array $defaultDatabaseIndexes

Fields that should be indexed, by class name

protected array $compositeFields

Cache of composite database field

protected array $tableNames

Cache of table names

Methods

public static 
create(mixed ...$args)

An implementation of the factory method, allows you to create an instance of a class

public static 
singleton(string $class = null)

Creates a class instance by the "singleton" design pattern.

public static 
config()

Get a configuration accessor for this class. Short hand for Config::inst()->get($this->class, .....).

public
mixed
uninherited(string $name)

Gets the uninherited value for the given config option

public
reset()

Clear cached table names

public
array
getTableNames()

Get all table names

public
string
sqlColumnForField(string $class, string $field, string $tablePrefix = null)

Given a DataObject class and a field on that class, determine the appropriate SQL for selecting / filtering on in a SQL string. Note that $class must be a valid class, not an arbitrary table.

public
string
tableName(string $class)

Get table name for the given class.

public
DataObject>
baseDataClass(string|object $class)

Returns the root class (the first to extend from DataObject) for the passed class.

public
string
baseDataTable(string|object $class)

Get the base table

public
array
fieldSpecs(string|DataObject $classOrInstance, int $options = 0)

Get all DB field specifications for a class, including ancestors and composite fields.

public
string|null
fieldSpec(string|DataObject $classOrInstance, string $fieldName, int $options = 0)

Get specifications for a single class field

public
DataObject>|null
tableClass(string $table)

Find the class for the given table

protected
cacheTableNames()

Cache all table names if necessary

protected
string
buildTableName(string $class)

Generate table name for a class.

public
array
databaseFields(string $class, bool $aggregated = true)

Return the complete map of fields to specification on this object, including fixed_fields.

public
string|null
databaseField(string $class, string $field, bool $aggregated = true)

Gets a single database field.

public
array
databaseIndexes(string $class, bool $aggregated = true)

No description

public
bool
classHasTable(string $class)

Check if the given class has a table

public
array
compositeFields(string $class, bool $aggregated = true)

Returns a list of all the composite if the given db field on the class is a composite field.

public
string|null
compositeField(string $class, string $field, bool $aggregated = true)

Get a composite field for a class

protected
cacheDatabaseFields(string $class)

Cache all database and composite fields for the given class.

protected
cacheDatabaseIndexes($class)

Cache all indexes for the given class. Will do nothing if already cached.

protected
array
cacheDefaultDatabaseIndexes(string $class)

Get "default" database indexable field types

protected
array
buildCustomDatabaseIndexes(string $class)

Look for custom indexes declared on the class

protected
buildSortDatabaseIndexes($class)

No description

protected
array
parseSortColumn(string $column)

Parses a specified column into a sort field and direction

public
string
tableForField(string $candidateClass, string $fieldName)

Returns the table name in the class hierarchy which contains a given field column for a DataObject. If the field does not exist, this will return null.

public
DataObject>|null
classForField(string $candidateClass, string $fieldName)

Returns the class name in the class hierarchy which contains a given field column for a DataObject. If the field does not exist, this will return null.

public
array|null
manyManyComponent(string $class, string $component)

Return information about a specific many_many component. Returns a numeric array.

protected
array
parseBelongsManyManyComponent(string $parentClass, string $component, string $specification)

Parse a belongs_many_many component to extract class and relationship name

public
array|null
manyManyExtraFieldsForComponent(string $class, string $component)

Return the many-to-many extra fields specification for a specific component.

public
string|null
hasManyComponent(string $class, string $component, bool $classOnly = true)

Return data for a specific has_many component.

public
string|null
hasOneComponent(string $class, string $component)

Return data for a specific has_one component.

public
bool
hasOneComponentHandlesMultipleRelations(string $class, string $component)

Check if a has_one relation handles multiple reciprocal has_many relations.

public
string|null
belongsToComponent(string $class, string $component, bool $classOnly = true)

Return data for a specific belongs_to component.

public
string|null
unaryComponent(string $class, string $component)

Check class for any unary component

protected
array
parseManyManyComponent(string $parentClass, string $component, string|array $specification)

No description

protected
string|null
getManyManyInverseRelationship(string $childClass, string $parentClass)

Find a many_many on the child class that points back to this many_many

public
string
getRemoteJoinField(string $class, string $component, string $type = 'has_many', bool $polymorphic = false)

Tries to find the database key on another object that is used to store a relationship to this class. If no join field can be found it defaults to 'ParentID'.

public
array
getHasManyComponentDetails(string $class, string $component)

No description

protected
string
checkManyManyFieldClass(string $parentClass, string $component, string $joinClass, array $specification, string $key)

Validate the to or from field on a has_many mapping class

protected
string
checkManyManyJoinClass(string $parentClass, string $component, array $specification)

No description

protected
checkRelationClass(string $class, string $component, string $relationClass, string $type)

Validate a given class is valid for a relation

Details

static Injectable create(mixed ...$args)

An implementation of the factory method, allows you to create an instance of a class

This method will defer class substitution to the Injector API, which can be customised via the Config API to declare substitution classes.

This can be called in one of two ways - either calling via the class directly, or calling on Object and passing the class name as the first parameter. The following are equivalent: $list = DataList::create(SiteTree::class); $list = SiteTree::get();

Parameters

mixed ...$args

Return Value

Injectable

static Injectable singleton(string $class = null)

Creates a class instance by the "singleton" design pattern.

It will always return the same instance for this class, which can be used for performance reasons and as a simple way to access instance methods which don't rely on instance data (e.g. the custom SilverStripe static handling).

Parameters

string $class

Optional classname to create, if the called class should not be used

Return Value

Injectable

The singleton instance

static Config_ForClass config()

Get a configuration accessor for this class. Short hand for Config::inst()->get($this->class, .....).

Return Value

Config_ForClass

mixed uninherited(string $name)

Gets the uninherited value for the given config option

Parameters

string $name

Return Value

mixed

reset()

Clear cached table names

array getTableNames()

Get all table names

Return Value

array

string sqlColumnForField(string $class, string $field, string $tablePrefix = null)

Given a DataObject class and a field on that class, determine the appropriate SQL for selecting / filtering on in a SQL string. Note that $class must be a valid class, not an arbitrary table.

The result will be a standard ANSI-sql quoted string in "Table"."Column" format.

Parameters

string $class

Class name (not a table).

string $field

Name of field that belongs to this class (or a parent class)

string $tablePrefix

Optional prefix for table (alias)

Return Value

string

The SQL identifier string for the corresponding column for this field

string tableName(string $class)

Get table name for the given class.

Note that this does not confirm a table actually exists (or should exist), but returns the name that would be used if this table did exist.

Parameters

string $class

Return Value

string

Returns the table name, or null if there is no table

DataObject> baseDataClass(string|object $class)

Returns the root class (the first to extend from DataObject) for the passed class.

Parameters

string|object $class

Return Value

DataObject>

Exceptions

InvalidArgumentException

string baseDataTable(string|object $class)

Get the base table

Parameters

string|object $class

Return Value

string

array fieldSpecs(string|DataObject $classOrInstance, int $options = 0)

Get all DB field specifications for a class, including ancestors and composite fields.

Parameters

string|DataObject $classOrInstance
int $options

Bitmask of options

  • UNINHERITED Limit to only this table
  • DB_ONLY Exclude virtual fields (such as composite fields), and only include fields with a db column.
  • INCLUDE_CLASS Prefix the field specification with the class name in RecordClass.Column(spec) format.

Return Value

array

List of fields, where the key is the field name and the value is the field specification.

string|null fieldSpec(string|DataObject $classOrInstance, string $fieldName, int $options = 0)

Get specifications for a single class field

Parameters

string|DataObject $classOrInstance

Name or instance of class

string $fieldName

Name of field to retrieve

int $options

Bitmask of options

  • UNINHERITED Limit to only this table
  • DB_ONLY Exclude virtual fields (such as composite fields), and only include fields with a db column.
  • INCLUDE_CLASS Prefix the field specification with the class name in RecordClass.Column(spec) format.

Return Value

string|null

Field will be a string in FieldClass(args) format, or RecordClass.FieldClass(args) format if using INCLUDE_CLASS. Will be null if no field is found.

DataObject>|null tableClass(string $table)

Find the class for the given table

Parameters

string $table

Return Value

DataObject>|null

The FQN of the class, or null if not found

protected cacheTableNames()

Cache all table names if necessary

protected string buildTableName(string $class)

Generate table name for a class.

Note: some DB schema have a hard limit on table name length. This is not enforced by this method. See dev/build errors for details in case of table name violation.

Parameters

string $class

Return Value

string

array databaseFields(string $class, bool $aggregated = true)

Return the complete map of fields to specification on this object, including fixed_fields.

"ID" will be included on every table.

Parameters

string $class

Class name to query from

bool $aggregated

Include fields in entire hierarchy, rather than just on this table

Return Value

array

Map of fieldname to specification, similar to DataObject::$db.

string|null databaseField(string $class, string $field, bool $aggregated = true)

Gets a single database field.

Parameters

string $class

Class name to query from

string $field

Field name

bool $aggregated

Include fields in entire hierarchy, rather than just on this table

Return Value

string|null

Field specification, or null if not a field

array databaseIndexes(string $class, bool $aggregated = true)

No description

Parameters

string $class
bool $aggregated

Return Value

array

bool classHasTable(string $class)

Check if the given class has a table

Parameters

string $class

Return Value

bool

array compositeFields(string $class, bool $aggregated = true)

Returns a list of all the composite if the given db field on the class is a composite field.

Will check all applicable ancestor classes and aggregate results.

Can be called directly on an object. E.g. Member::composite_fields(), or Member::composite_fields(null, true) to aggregate.

Includes composite has_one (Polymorphic) fields

Parameters

string $class

Name of class to check

bool $aggregated

Include fields in entire hierarchy, rather than just on this table

Return Value

array

List of composite fields and their class spec

string|null compositeField(string $class, string $field, bool $aggregated = true)

Get a composite field for a class

Parameters

string $class

Class name to query from

string $field

Field name

bool $aggregated

Include fields in entire hierarchy, rather than just on this table

Return Value

string|null

Field specification, or null if not a field

protected cacheDatabaseFields(string $class)

Cache all database and composite fields for the given class.

Will do nothing if already cached

Parameters

string $class

Class name to cache

protected cacheDatabaseIndexes($class)

Cache all indexes for the given class. Will do nothing if already cached.

Parameters

$class

protected array cacheDefaultDatabaseIndexes(string $class)

Get "default" database indexable field types

Parameters

string $class

Return Value

array

protected array buildCustomDatabaseIndexes(string $class)

Look for custom indexes declared on the class

Parameters

string $class

Return Value

array

Exceptions

InvalidArgumentException
InvalidArgumentException

protected buildSortDatabaseIndexes($class)

No description

Parameters

$class

protected array parseSortColumn(string $column)

Parses a specified column into a sort field and direction

Parameters

string $column

String to parse containing the column name

Return Value

array

Resolved table and column.

string tableForField(string $candidateClass, string $fieldName)

Returns the table name in the class hierarchy which contains a given field column for a DataObject. If the field does not exist, this will return null.

Parameters

string $candidateClass
string $fieldName

Return Value

string

DataObject>|null classForField(string $candidateClass, string $fieldName)

Returns the class name in the class hierarchy which contains a given field column for a DataObject. If the field does not exist, this will return null.

Parameters

string $candidateClass
string $fieldName

Return Value

DataObject>|null

array|null manyManyComponent(string $class, string $component)

Return information about a specific many_many component. Returns a numeric array.

The first item in the array will be the class name of the relation.

Standard many_many return type is:

[

, Name of class for relation. E.g. "Categories" , The class that relation is defined in e.g. "Product" , The target class of the relation e.g. "Category" , The field name pointing to 's table e.g. "ProductID". , The field name pointing to 's table e.g. "CategoryID". The join table between the two classes e.g. "Product_Categories". If the class name is 'ManyManyThroughList' then this is the name of the has_many relation. ]

Parameters

string $class

Name of class to get component for

string $component

The component name

Return Value

array|null

protected array parseBelongsManyManyComponent(string $parentClass, string $component, string $specification)

Parse a belongs_many_many component to extract class and relationship name

Parameters

string $parentClass

Name of class

string $component

Name of relation on class

string $specification

specification for this belongs_many_many

Return Value

array

Array with child class and relation name

array|null manyManyExtraFieldsForComponent(string $class, string $component)

Return the many-to-many extra fields specification for a specific component.

Parameters

string $class
string $component

Return Value

array|null

string|null hasManyComponent(string $class, string $component, bool $classOnly = true)

Return data for a specific has_many component.

Parameters

string $class

Parent class

string $component
bool $classOnly

If this is TRUE, than any has_many relationships in the form "ClassName.Field" will have the field data stripped off. It defaults to TRUE.

Return Value

string|null

string|null hasOneComponent(string $class, string $component)

Return data for a specific has_one component.

Parameters

string $class
string $component

Return Value

string|null

bool hasOneComponentHandlesMultipleRelations(string $class, string $component)

Check if a has_one relation handles multiple reciprocal has_many relations.

Parameters

string $class
string $component

Return Value

bool

True if the relation exists and handles multiple reciprocal has_many relations.

string|null belongsToComponent(string $class, string $component, bool $classOnly = true)

Return data for a specific belongs_to component.

Parameters

string $class
string $component
bool $classOnly

If this is TRUE, than any has_many relationships in the form "ClassName.Field" will have the field data stripped off. It defaults to TRUE.

Return Value

string|null

string|null unaryComponent(string $class, string $component)

Check class for any unary component

Alias for hasOneComponent() ?: belongsToComponent()

Parameters

string $class
string $component

Return Value

string|null

protected array parseManyManyComponent(string $parentClass, string $component, string|array $specification)

No description

Parameters

string $parentClass

Parent class name

string $component

ManyMany name

string|array $specification

Declaration of many_many relation type

Return Value

array

protected string|null getManyManyInverseRelationship(string $childClass, string $parentClass)

Find a many_many on the child class that points back to this many_many

Parameters

string $childClass
string $parentClass

Return Value

string|null

string getRemoteJoinField(string $class, string $component, string $type = 'has_many', bool $polymorphic = false)

Tries to find the database key on another object that is used to store a relationship to this class. If no join field can be found it defaults to 'ParentID'.

If the remote field is polymorphic then $polymorphic is set to true, and the return value is in the form 'Relation' instead of 'RelationID', referencing the composite DBField.

Parameters

string $class
string $component

Name of the relation on the current object pointing to the remote object.

string $type

the join type - either 'has_many' or 'belongs_to'

bool $polymorphic

Flag set to true if the remote join field is polymorphic.

Return Value

string

Exceptions

Exception

array getHasManyComponentDetails(string $class, string $component)

No description

Parameters

string $class
string $component

Return Value

array

protected string checkManyManyFieldClass(string $parentClass, string $component, string $joinClass, array $specification, string $key)

Validate the to or from field on a has_many mapping class

Parameters

string $parentClass

Name of parent class

string $component

Name of many_many component

string $joinClass

Class for the joined table

array $specification

Complete many_many specification

string $key

Name of key to check ('from' or 'to')

Return Value

string

Class that matches the given relation

Exceptions

InvalidArgumentException

protected string checkManyManyJoinClass(string $parentClass, string $component, array $specification)

No description

Parameters

string $parentClass

Name of parent class

string $component

Name of many_many component

array $specification

Complete many_many specification

Return Value

string

Name of join class

protected checkRelationClass(string $class, string $component, string $relationClass, string $type)

Validate a given class is valid for a relation

Parameters

string $class

Parent class

string $component

Component name

string $relationClass

Candidate class to check

string $type

Relation type (e.g. has_one)