phpcr/src/PHPCR/SessionInterface.php

This method quietly returns if the access request is permitted, or throws a \PHPCR\Security\AccessControlException otherwise. The actions parameter is a comma separated list of action strings.

The following action strings are defined:

• add_node: If checkPermission(path, "add_node") returns quietly, then this Session has permission to add a node at path, otherwise permission is denied.
• set_property: If checkPermission(path, "set_property") returns quietly, then this Session has permission to set (add or change) a property at path, otherwise permission is denied.
• remove: If checkPermission(path, "remove") returns quietly, then this Session has permission to remove an item at path, otherwise permission is denied.
• read: If checkPermission(path, "read") returns quietly, then this Session has permission to retrieve (and read the value of, in the case of a property) an item at path, otherwise permission is denied.

When more than one action is specified in the actions parameter, this method will only return true if this Session has permission to perform all of the listed actions at the specified path.

The information returned through this method will only reflect the access control status (both JCR defined and implementation-specific) and not other restrictions that may exist, such as node type constraints. For example, even though hasPermission may indicate that a particular Session may add a property at /A/B/C, the node type of the node at /A/B may prevent the addition of a property called C.

The resulting XML is in the document view form. Note that $absPath must be the path of a node, not a property.

If $skipBinary is true then any properties of PropertyType::BINARY will be serialized as if they are empty. That is, the existence of the property will be serialized, but its content will not appear in the serialized output (the value of the attribute will be empty). If $skipBinary is false then the actual value(s) of each BINARY property is recorded using Base64 encoding.

If $noRecurse is true then only the node at $absPath and its properties, but not its child nodes, are serialized. If $noRecurse is false then the entire subgraph rooted at $absPath is serialized.

If the user lacks read access to some subsection of the specified tree, that section simply does not get serialized, since, from the user's point of view, it is not there.

The serialized output will reflect the state of the current workspace as modified by the state of this Session. This means that pending changes (regardless of whether they are valid according to node type constraints) and all namespace mappings in the namespace registry, as modified by the current session-mappings, are reflected in the output.

The output XML will be encoded in UTF-8.

The resulting XML is in the system view form. Note that $absPath must be the path of a node, not a property.

If $skipBinary is true then any properties of PropertyType::BINARY will be serialized as if they are empty. That is, the existence of the property will be serialized, but its content will not appear in the serialized output (the element will have no content). Note that in the case of multi-value BINARY properties, the number of values in the property will be reflected in the serialized output, though they will all be empty. If $skipBinary is false then the actual value(s) of each BINARY property is recorded using Base64 encoding.

If $noRecurse is true then only the node at $absPath and its properties, but not its child nodes, are serialized. If $noRecurse is false then the entire subgraph rooted at $absPath is serialized.

If the user lacks read access to some subsection of the specified tree, that section simply does not get serialized, since, from the user's point of view, it is not there.

The serialized output will reflect the state of the current workspace as modified by the state of this Session. This means that pending changes (regardless of whether they are valid according to node type constraints) and all namespace mappings in the namespace registry, as modified by the current session-mappings, are reflected in the output.

The output XML will be encoded in UTF-8.

See getAttributeNames().

Not all Credentials implementations will contain attributes (though, for example, SimpleCredentials does allow for them). This method returns an empty array if the Credentials instance did not provide attributes.

If no such node exists, then it returns the property at the specified path.

This method should only be used if the application does not know whether the item at the indicated path is property or node. In cases where the application has this information, either SessionInterface::getNode() or SessionInterface::getProperty() should be used, as appropriate. In many repository implementations the node and property-specific methods are likely to be more efficient than getItem.

If $depthHint is set, the implementation may cache the subtree rooted at $absPath to depth $depthHint in preparation for possible future access requests by the client.

The parameter $depthHint may be used by an implementation to improve the efficiency of access for nodes in the subtree rooted at $absPath. This may, for example, be advantageous to client-server implementations by reducing round-trips to the server. An implementation is free to ignore the $depthHint parameter.

If the implementation does not ignore $depthHint then the following rules apply:

$depthHint < 0: Equivalent to omitting the $deptHint $depthHint = 0: The node at $absPath and all its properties are retrieved. No child nodes (nor any further descendants) are retrieved. This is referred to as a shallow getNode.

$depthHint > 0: The node at absPath and all its properties are retrieved as well as all descendant nodes (and their respective properties) up to degree $depthHint. A $depthHint of 1 retrieves the node at $absPath and all its child nodes. A $depthHint of 2 retrieves the node at $absPath, all its child nodes and all their child nodes in turn. And so on.

An implementation is free to set a limit on the amount of data cached due to the $depthHint parameter. Thus, the implementation may fail to retrieve to the full depth requested in cases where that depth is large and the data size of the nodes and properties in the subtree is also large. In order to guarantee a retrieval to the maximum depth possible, the client can set $depthHint to PHP_INT_MAX.

Applies to both referenceable and non-referenceable nodes.

If none of the specified paths leads to an existing and accessible node then an empty iterator is returned.

Applies to both referenceable and non-referenceable nodes. If none of the specified identifiers refer to an existing and accessible node then an empty iterator is returned.

If none of the specified paths leads to an existing and accessible property then an empty iterator is returned.

This node is the main access point to the content of the workspace.

How the user ID is set is up to the implementation, it may be a string passed in as part of the credentials or it may be a string acquired in some other way. This method is free to return an "anonymous user ID" or null.

• Permissions granted to the current user, including access control privileges.
• Current state of the target object (reflecting locks, checkin/checkout status, retention and hold status etc.).
• Repository capabilities.
• Node type-enforced restrictions.
• Repository configuration-specific restrictions.

The implementation of this method is best effort: returning false guarantees that the operation cannot be performed, but returning true does not guarantee the opposite.

The methodName parameter identifies the method in question by its name as defined in the phpdoc.

The target parameter identifies the object on which the specified method is called.

The arguments parameter contains a hash map consisting of parameter name mapping to parameter value.

For example, given a Session $s and Node $n then

$p['relPath'] = 'foo';
$b = $s->hasCapability("addNode", $n, $p);

will result in $b === false if a child node called foo cannot be added to the node $n within the session $s.

Returns true if this session holds pending (that is, unsaved) changes; otherwise returns false.

Returns true if this Session has permission to perform the specified actions at the specified absPath and false otherwise. The actions parameter is a comma separated list of action strings.

The following action strings are defined:

• add_node: If hasPermission(path, "add_node") returns true, then this Session has permission to add a node at path.
• set_property: If hasPermission(path, "set_property") returns true, then this Session has permission to set (add or change) a property at path.
• remove: If hasPermission(path, "remove") returns true, then this Session has permission to remove an item at path.
• read: If hasPermission(path, "read") returns true, then this Session has permission to retrieve (and read the value of, in the case of a property) an item at path.

When more than one action is specified in the actions parameter, this method will only return true if this Session has permission to perform all of the listed actions at the specified path.

The information returned through this method will only reflect the access control status (both JCR defined and implementation-specific) and not other restrictions that may exist, such as node type constraints. For example, even though hasPermission may indicate that a particular Session may add a property at /A/B/C, the node type of the node at /A/B may prevent the addition of a property called C.

Allows the current user to acquire a new session using incomplete or relaxed credentials requirements (perhaps including a user name but no password, for example), assuming that this Session gives them that permission. This method can be used to "impersonate" another user or to clone the current session by passing in the same credentials that were used to acquire the current session.

The new Session is tied to a new Workspace instance. In other words, Workspace instances are not re-used. However, the Workspace instance returned represents the same actual persistent workspace entity in the repository as is represented by the Workspace object tied to the current Session.

If the incoming XML does not appear to be a JCR system view XML document then it is interpreted as a document view XML document.

The tree of new items is built in the transient storage of the Session. In order to persist the new content, save must be called. The advantage of this through-the-session method is that (depending on what constraint checks the implementation leaves until save) structures that violate node type constraints can be imported, fixed and then saved. The disadvantage is that a large import will result in a large cache of pending nodes in the session. See WorkspaceInterface::importXML() for a version of this method that does not go through the Session.

The flag $uuidBehavior governs how the identifiers of incoming nodes are handled. There are four options:

• ImportUUIDBehavior::IMPORT_UUID_CREATE_NEW: Incoming nodes are added in the same way that new node is added with Node::addNode(). That is, they are either assigned newly created identifiers upon addition or upon save (depending on the implementation, see 4.9.1.1 When Identifiers are Assigned in the specification). In either case, identifier collisions will not occur. (Weak)references will point to the original node if existing, to the imported node with matching id otherwise.
• ImportUUIDBehavior::IMPORT_UUID_COLLISION_REMOVE_EXISTING: If an incoming node has the same identifier as a node already existing in the workspace then the already existing node (and its subgraph) is removed from wherever it may be in the workspace before the incoming node is added. Note that this can result in nodes "disappearing" from locations in the workspace that are remote from the location to which the incoming subgraph is being written. Both the removal and the new addition will be dispatched on save.
• ImportUUIDBehavior::IMPORT_UUID_COLLISION_REPLACE_EXISTING: If an incoming node has the same identifier as a node already existing in the workspace, then the already-existing node is replaced by the incoming node in the same position as the existing node. Note that this may result in the incoming subgraph being disaggregated and "spread around" to different locations in the workspace. In the most extreme case this behavior may result in no node at all being added as child of parentAbsPath. This will occur if the topmost element of the incoming XML has the same identifier as an existing node elsewhere in the workspace. The change will be dispatched on save.
• ImportUUIDBehavior::IMPORT_UUID_COLLISION_THROW: If an incoming node has the same identifier as a node already existing in the workspace then an ItemExistsException is thrown.

Unlike WorkspaceInterface::importXML(), this method does not necessarily enforce all node type constraints during deserialization. Those that would be immediately enforced in a normal write method (NodeInterface::addNode(), NodeInterface::setProperty() etc.) of this implementation cause an immediate ConstraintViolationException during deserialization. All other constraints are checked on save, just as they are in normal write operations. However, which node type constraints are enforced depends upon whether node type information in the imported data is respected, and this is an implementation-specific issue.

Returns true if this Session object is usable by the client. Otherwise, returns false.

A usable Session is one that is neither logged-out, timed-out nor in any other way disconnected from the repository.

Returns true if an item exists at absPath and this Session has read access to it; otherwise returns false.

This method should be called when a Session is no longer needed.

This is a session-write method and therefor requires a save to dispatch the change.

The identifiers of referenceable nodes must not be changed by a move. The identifiers of non-referenceable nodes may change.

A ConstraintViolationException is thrown either immediately, on dispatch or on persist, if performing this operation would violate a node type or implementation-specific constraint. Implementations may differ on when this validation is performed.

As well, a ConstraintViolationException will be thrown on persist if an attempt is made to separately save either the source or destination node.

Note that this behaviour differs from that of WorkspaceInterface::move( $srcAbsPath, $destAbsPath), which is a workspace-write method and therefore immediately dispatches changes.

The destAbsPath provided must not have an index on its final element. If ordering is supported by the node type of the parent node of the new location, then the newly moved node is appended to the end of the child node list.

This method cannot be used to move an individual property by itself. It moves an entire node and its subgraph.

Returns true if a node exists at absPath and this Session has read access to it; otherwise returns false.

Returns true if a property exists at absPath and this Session has read access to it; otherwise returns false.

If keepChanges is false, this method discards all pending changes currently recorded in this Session and returns all items to reflect the current saved state. Outside a transaction this state is simply the current state of persistent storage. Within a transaction, this state will reflect persistent storage as modified by changes that have been saved but not yet committed.

If keepChanges is true then pending change are not discarded but items that do not have changes pending have their state refreshed to reflect the current saved state, thus revealing changes made by other sessions.

Implementors note: For performance reasons, implementations should only mark nodes as dirty and reload them from the backend only if actually needed.

This is a session-write method and therefore requires a save in order to dispatch the change.

If a node with same-name siblings is removed, this decrements by one the indices of all the siblings with indices greater than that of the removed node. In other words, a removal compacts the array of same-name siblings and causes the minimal re-numbering required to maintain the original order but leave no gaps in the numbering.

If validation of all pending changes succeeds, then this change information is cleared from the Session.

If the save occurs outside a transaction, the changes are dispatched and persisted. Upon being persisted the changes become potentially visible to other Sessions bound to the same persistent workspace.

If the save occurs within a transaction, the changes are dispatched but are not persisted until the transaction is committed.

If validation fails, then no pending changes are dispatched and they remain recorded on the Session. There is no best-effort or partial save.

Within the scope of this Session, this method maps uri to prefix. The remapping only affects operations done through this Session. To clear all remappings, the client must acquire a new Session. All local mappings already present in the Session that include either the specified prefix or the specified uri are removed and the new mapping is added.