PHP Class Google\Cloud\Datastore\Key

Keys are unique identifiers for entities. Keys may be considered either "named" or "incomplete". A named Key is one in which each element of the Key path specify a Kind and a Name or ID. An incomplete Key omits the Name or ID from the final path element. Named Keys are required for any lookup, update, upsert or delete operations. They may also be used for inserting records, so long as you are certain that the identifier is available in Datastore. Incomplete Keys may be used for inserting records into Datastore. When an incomplete Key is used, Datastore will allocate an ID before inserting. Incomplete Keys are useful for guaranteeing the availability of an identifier without requiring an additional operation to check whether a given name or ID is available. Key state can be checked by calling Key::state(). The return will be one of Key::STATE_NAMED or Key::STATE_INCOMPLETE. Example: use Google\Cloud\ServiceBuilder; $cloud = new ServiceBuilder(); $datastore = $cloud->datastore(); $key = $datastore->key('Person', 'Bob'); Keys with complex paths can be constructed with additional method calls. $key = $datastore->key('Person', 'Bob'); $key->ancestor('Parents', 'Joe'); $key->ancestor('Grandparents', 'Barb'); Path elements can also be appended, so long as the current last path element contains a kind and identifier. $key = $datastore->key('Grandparents', 'Barb'); $key->pathElement('Parents', 'Joe'); $key->pathElement('Person'); $key->pathElement('Child', 'Dave'); // Error here.
See also: https://cloud.google.com/datastore/reference/rest/v1/Key Key
Inheritance: implements JsonSerializabl\JsonSerializable, use trait Google\Cloud\ArrayTrait, use trait DatastoreTrait
显示文件 Open project: GoogleCloudPlatform/gcloud-php Class Usage Examples

Public Methods

Method Description
__construct ( string $projectId, array $options = [] ) Create a Key.
__toString ( ) Represent the path as a string.
ancestor ( string $kind, string | integer $identifier, array $options = [] ) : Key Add a path element to the beginning of the Key path.
ancestorKey ( Key $key ) : Key Use another Key's path as the current Key's ancestor
jsonSerialize ( )
keyObject ( ) : array Get the key object formatted for the datastore service.
path ( ) : array Get the key path
pathElement ( string $kind, string | integer $identifier = null, array $options = [] ) : Key Add a path element to the end of the Key path
pathEnd ( ) : array Get the last pathElement in the key
pathEndIdentifier ( ) : string | integer | null Get the last pathElement identifier.
pathEndIdentifierType ( ) : string | null Get the last pathElement identifier type.
setLastElementIdentifier ( string $value, string $type = Key::TYPE_ID ) : void Set the value of the last path element in a Key
state ( ) : boolean Check if the Key is considered Named or Incomplete.

Private Methods

Method Description
determineIdentifierType ( mixed $identifier, string | null $identifierType ) : string Determine whether the given identifier is an ID or a Name
normalizeElement ( string $kind, mixed $identifier, string $identifierType ) : array Determine the identifier type and return the valid pathElement
normalizePath ( array $path ) : array Normalize the internal representation of a path

Method Details

__construct() public method

Create a Key.
public __construct ( string $projectId, array $options = [] )
$projectId string The project ID.
$options array [optional] { Configuration Options @type string $namespaceId Partitions data under a namespace. Useful for [Multitenant Projects](https://cloud.google.com/datastore/docs/concepts/multitenancy). Applications with no need for multitenancy should not set this value. @type array $path The initial Key path. }

__toString() public method

Represent the path as a string.
public __toString ( )

ancestor() public method

Example: $key->ancestor('Person', 'Jane'); In cases where the identifier type is ambiguous, you can choose the type to be used. $key->ancestor('Robots', '1337', [ 'identifierType' => Key::TYPE_NAME ]);
See also: https://cloud.google.com/datastore/reference/rest/v1/Key#PathElement PathElement
public ancestor ( string $kind, string | integer $identifier, array $options = [] ) : Key
$kind string The kind.
$identifier string | integer The name or ID of the object.
$options array { Configuration Options @type string $identifierType [optional] If omitted, the type will be determined internally. Setting this to either `Key::TYPE_ID` or `Key::TYPE_NAME` will force the pathElement identifier type. }
return Key

ancestorKey() public method

Given key path will be prepended to any path elements on the current key. Example: $parent = $datastore->key('Person', 'Dad'); $key->ancestorKey($parent);
public ancestorKey ( Key $key ) : Key
$key Key The ancestor Key.
return Key

jsonSerialize() public method

public jsonSerialize ( )

keyObject() public method

Get the key object formatted for the datastore service.
public keyObject ( ) : array
return array

path() public method

Example: $path = $key->path();
public path ( ) : array
return array

pathElement() public method

If the previous pathElement is incomplete (has no name or ID specified), an InvalidArgumentException will be thrown. Once an incomplete pathElement is given, the key cannot be extended any further. Example: $key->pathElement('Person', 'Jane'); In cases where the identifier type is ambiguous, you can choose the type to be used. $key->pathElement('Robots', '1337', [ 'identifierType' => Key::TYPE_NAME ]);
See also: https://cloud.google.com/datastore/reference/rest/v1/Key#PathElement PathElement
public pathElement ( string $kind, string | integer $identifier = null, array $options = [] ) : Key
$kind string The kind.
$identifier string | integer [optional] The name or ID of the object.
$options array { Configuration Options @type string $identifierType [optional] If omitted, the type will be determined internally. Setting this to either `Key::TYPE_ID` or `Key::TYPE_NAME` will force the pathElement identifier type. }
return Key

pathEnd() public method

Example: $lastPathElement = $key->pathEnd();
public pathEnd ( ) : array
return array

pathEndIdentifier() public method

If the key is incomplete, returns null. Example: $lastPathElementIndentifier = $key->pathEndIdentifier();
public pathEndIdentifier ( ) : string | integer | null
return string | integer | null

pathEndIdentifierType() public method

If the key is incomplete, returns null. Example: $lastPathElementIdentifierType = $key->pathEndIdentifierType();
public pathEndIdentifierType ( ) : string | null
return string | null

setLastElementIdentifier() public method

This method is used internally when IDs are allocated to existing instances of a Key. It should not generally be used externally. Example: $key = $datastore->key('Person'); $key->setLastElementIdentifier('Bob', Key::TYPE_NAME);
public setLastElementIdentifier ( string $value, string $type = Key::TYPE_ID ) : void
$value string The value of the ID or Name.
$type string [optional] 'id' or 'name'. **Defaults to** `"id"`.
return void

state() public method

Use Key::STATE_NAMED and Key::STATE_INCOMPLETE to check value. Example: An incomplete key does not have an ID on its last path element. $key = $datastore->key('parent', 1234) ->pathElement('child'); if ($key->state() === Key::STATE_INCOMPLETE) { echo 'Key is incomplete!'; } A named key has a kind and an identifier on each path element. $key = $datastore->key('parent', 1234) ->pathElement('child', 4321); if ($key->state() === Key::STATE_NAMED) { echo 'Key is named!'; }
public state ( ) : boolean
return boolean