This class represents a set of properties that are going to be updated. More...

Inheritance diagram for Sabre\DAV\PropPatch:

Collaboration diagram for Sabre\DAV\PropPatch:

Public Member Functions
	__construct (array $mutations)
	Constructor. More...

	handle ($properties, callable $callback)
	Call this function if you wish to handle updating certain properties. More...

	handleRemaining (callable $callback)
	Call this function if you wish to handle all properties that haven't been handled by anything else yet. More...

	setResultCode ($properties, $resultCode)
	Sets the result code for one or more properties. More...

	setRemainingResultCode ($resultCode)
	Sets the result code for all properties that did not have a result yet. More...

	getRemainingMutations ()
	Returns the list of properties that don't have a result code yet. More...

	getRemainingValues ()
	Returns the list of properties that don't have a result code yet. More...

	commit ()
	Performs the actual update, and calls all callbacks. More...

	getResult ()
	Returns the result of the operation. More...

	getMutations ()
	Returns the full list of mutations. More...

Protected Attributes
	$mutations

	$result = []

	$propertyUpdateCallbacks = []

	$failed = false

Private Member Functions
	doCallBackSingleProp ($propertyName, callable $callback)
	Executes a property callback with the single-property syntax. More...

	doCallBackMultiProp (array $propertyList, callable $callback)
	Executes a property callback with the multi-property syntax. More...

Detailed Description

This class represents a set of properties that are going to be updated.

Usually this is simply a PROPPATCH request, but it can also be used for internal updates.

Property updates must always be atomic. This means that a property update must either completely succeed, or completely fail.

Copyright: Copyright (C) fruux GmbH (https://fruux.com/)

Author: Evert Pot (http://evertpot.com/) http://sabre.io/license/ Modified BSD License

Definition at line 20 of file PropPatch.php.

Constructor & Destructor Documentation

◆ __construct()

Sabre\DAV\PropPatch::__construct ( array $mutations )

Constructor.

Parameters

array $mutations A list of updates

Definition at line 59 of file PropPatch.php.

References Sabre\DAV\PropPatch\$mutations.

                                            {
 
         $this->mutations = $mutations;
 
     }

Member Function Documentation

◆ commit()

Sabre\DAV\PropPatch::commit ( )

Performs the actual update, and calls all callbacks.

This method returns true or false depending on if the operation was successful.

Returns: bool

If anywhere in this operation updating a property failed, we must update all other properties accordingly.

Definition at line 225 of file PropPatch.php.

References Sabre\DAV\PropPatch\$failed.

Referenced by Sabre\DAV\Server\createCollection().

                       {
 
         // First we validate if every property has a handler
         foreach ($this->mutations as $propertyName => $value) {
 
             if (!isset($this->result[$propertyName])) {
                 $this->failed = true;
                 $this->result[$propertyName] = 403;
             }
 
         }
 
         foreach ($this->propertyUpdateCallbacks as $callbackInfo) {
 
             if ($this->failed) {
                 break;
             }
             if (is_string($callbackInfo[0])) {
                 $this->doCallbackSingleProp($callbackInfo[0], $callbackInfo[1]);
             } else {
                 $this->doCallbackMultiProp($callbackInfo[0], $callbackInfo[1]);
             }
 
         }
 
         if ($this->failed) {
 
             foreach ($this->result as $propertyName => $status) {
                 if ($status === 202) {
                     // Failed dependency
                     $this->result[$propertyName] = 424;
                 }
             }
 
         }
 
         return !$this->failed;
 
     }

Here is the caller graph for this function:

◆ doCallBackMultiProp()

Sabre\DAV\PropPatch::doCallBackMultiProp	(	array	$propertyList,
		callable	$callback
	)

private

Executes a property callback with the multi-property syntax.

Parameters

array	$propertyList
callable	$callback

Returns: void

Definition at line 310 of file PropPatch.php.

References Sabre\DAV\PropPatch\$result.

                                                                                   {
 
         $argument = [];
         foreach ($propertyList as $propertyName) {
             $argument[$propertyName] = $this->mutations[$propertyName];
         }
 
         $result = $callback($argument);
 
         if (is_array($result)) {
             foreach ($propertyList as $propertyName) {
                 if (!isset($result[$propertyName])) {
                     $resultCode = 500;
                 } else {
                     $resultCode = $result[$propertyName];
                 }
                 if ($resultCode >= 400) {
                     $this->failed = true;
                 }
                 $this->result[$propertyName] = $resultCode;
 
             }
         } elseif ($result === true) {
 
             // Success
             foreach ($argument as $propertyName => $propertyValue) {
                 $this->result[$propertyName] = is_null($propertyValue) ? 204 : 200;
             }
 
         } elseif ($result === false) {
             // Fail :(
             $this->failed = true;
             foreach ($propertyList as $propertyName) {
                 $this->result[$propertyName] = 403;
             }
         } else {
             throw new UnexpectedValueException('A callback sent to handle() did not return an array or a bool');
         }
 
     }

◆ doCallBackSingleProp()

Sabre\DAV\PropPatch::doCallBackSingleProp	(		$propertyName,
		callable	$callback
	)

private

Executes a property callback with the single-property syntax.

Parameters

string	$propertyName
callable	$callback

Returns: void

Definition at line 276 of file PropPatch.php.

References Sabre\DAV\PropPatch\$result.

                                                                              {
 
         $result = $callback($this->mutations[$propertyName]);
         if (is_bool($result)) {
             if ($result) {
                 if (is_null($this->mutations[$propertyName])) {
                     // Delete
                     $result = 204;
                 } else {
                     // Update
                     $result = 200;
                 }
             } else {
                 // Fail
                 $result = 403;
             }
         }
         if (!is_int($result)) {
             throw new UnexpectedValueException('A callback sent to handle() did not return an int or a bool');
         }
         $this->result[$propertyName] = $result;
         if ($result >= 400) {
             $this->failed = true;
         }
 
     }

◆ getMutations()

Sabre\DAV\PropPatch::getMutations ( )

Returns the full list of mutations.

Returns: array

Definition at line 367 of file PropPatch.php.

References Sabre\DAV\PropPatch\$mutations.

Referenced by Sabre\DAV\TreeFileTester\propPatch(), and Sabre\DAV\CorePlugin\propPatchProtectedPropertyCheck().

                             {
 
         return $this->mutations;
 
     }

Here is the caller graph for this function:

◆ getRemainingMutations()

Sabre\DAV\PropPatch::getRemainingMutations ( )

Returns the list of properties that don't have a result code yet.

This method returns a list of property names, but not its values.

Returns: string[]

Definition at line 184 of file PropPatch.php.

References $remaining.

Referenced by Sabre\DAV\Server\createCollection(), Sabre\DAV\PropPatch\handleRemaining(), and Sabre\DAV\PropPatch\setRemainingResultCode().

                                      {
 
         $remaining = [];
         foreach ($this->mutations as $propertyName => $propValue) {
             if (!isset($this->result[$propertyName])) {
                 $remaining[] = $propertyName;
             }
         }
 
         return $remaining;
 
     }

Here is the caller graph for this function:

◆ getRemainingValues()

Sabre\DAV\PropPatch::getRemainingValues ( )

Returns the list of properties that don't have a result code yet.

This method returns list of properties and their values.

Returns: array

Definition at line 204 of file PropPatch.php.

References $remaining.

Referenced by Sabre\CalDAV\CalendarHome\createExtendedCollection().

                                   {
 
         $remaining = [];
         foreach ($this->mutations as $propertyName => $propValue) {
             if (!isset($this->result[$propertyName])) {
                 $remaining[$propertyName] = $propValue;
             }
         }
 
         return $remaining;
 
     }

Here is the caller graph for this function:

◆ getResult()

Sabre\DAV\PropPatch::getResult ( )

Returns the result of the operation.

Returns: array

Definition at line 356 of file PropPatch.php.

References Sabre\DAV\PropPatch\$result.

Referenced by Sabre\DAV\Server\createCollection().

                          {
 
         return $this->result;
 
     }

Here is the caller graph for this function:

◆ handle()

Sabre\DAV\PropPatch::handle	(		$properties,
		callable	$callback
	)

Call this function if you wish to handle updating certain properties.

For instance, your class may be responsible for handling updates for the {DAV:}displayname property.

In that case, call this method with the first argument "{DAV:}displayname" and a second argument that's a method that does the actual updating.

It's possible to specify more than one property as an array.

The callback must return a boolean or an it. If the result is true, the operation was considered successful. If it's false, it's consided failed.

If the result is an integer, we'll use that integer as the http status code associated with the operation.

Parameters

	string\|string[]	$properties
callable	$callback

Returns: void

Definition at line 87 of file PropPatch.php.

Referenced by Sabre\CalDAV\Schedule\Plugin\propPatch(), Sabre\DAV\HTTPPreferParsingTest\testproppatchMinimal(), and Sabre\DAV\ServerUpdatePropertiesTest\testUpdatePropertiesEventSuccess().

                                                      {
 
         $usedProperties = [];
         foreach ((array)$properties as $propertyName) {
 
             if (array_key_exists($propertyName, $this->mutations) && !isset($this->result[$propertyName])) {
 
                 $usedProperties[] = $propertyName;
                 // HTTP Accepted
                 $this->result[$propertyName] = 202;
             }
 
         }
 
         // Only registering if there's any unhandled properties.
         if (!$usedProperties) {
             return;
         }
         $this->propertyUpdateCallbacks[] = [
             // If the original argument to this method was a string, we need
             // to also make sure that it stays that way, so the commit function
             // knows how to format the arguments to the callback.
             is_string($properties) ? $properties : $usedProperties,
             $callback
         ];
 
     }

Here is the caller graph for this function:

◆ handleRemaining()

Sabre\DAV\PropPatch::handleRemaining ( callable $callback )

Call this function if you wish to handle all properties that haven't been handled by anything else yet.

Note that you effectively claim with this that you promise to process all properties that are coming in.

Parameters

callable $callback

Returns: void

Definition at line 123 of file PropPatch.php.

References Sabre\DAV\PropPatch\getRemainingMutations().

Referenced by Sabre\DAV\Mock\PropertiesCollection\propPatch(), Sabre\DAV\PropertyStorage\Backend\Mock\propPatch(), Sabre\DAV\PropertyStorage\Backend\PDO\propPatch(), Sabre\DAV\ServerUpdatePropertiesTest\testUpdatePropertiesEventFail(), and Sabre\DAV\ServerUpdatePropertiesTest\testUpdatePropertiesProtected().

                                                  {
 
         $properties = $this->getRemainingMutations();
         if (!$properties) {
             // Nothing to do, don't register callback
             return;
         }
 
         foreach ($properties as $propertyName) {
             // HTTP Accepted
             $this->result[$propertyName] = 202;
 
             $this->propertyUpdateCallbacks[] = [
                 $properties,
                 $callback
             ];
         }
 
     }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setRemainingResultCode()

Sabre\DAV\PropPatch::setRemainingResultCode ( $resultCode )

Sets the result code for all properties that did not have a result yet.

Parameters

int $resultCode

Returns: void

Definition at line 168 of file PropPatch.php.

References Sabre\DAV\PropPatch\getRemainingMutations(), and Sabre\DAV\PropPatch\setResultCode().

Referenced by Sabre\CalDAV\CalendarHome\createExtendedCollection(), and Sabre\DAV\TreeFileTester\propPatch().

                                                  {
 
         $this->setResultCode(
             $this->getRemainingMutations(),
             $resultCode
         );
 
     }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setResultCode()

Sabre\DAV\PropPatch::setResultCode	(	$properties,
		$resultCode
	)

Sets the result code for one or more properties.

Parameters

	string\|string[]	$properties
int	$resultCode

Returns: void

Definition at line 150 of file PropPatch.php.

Referenced by Sabre\DAV\CorePlugin\propPatchProtectedPropertyCheck(), Sabre\DAV\PropPatch\setRemainingResultCode(), and Sabre\DAV\ServerUpdatePropertiesTest\testUpdatePropertiesEventFail().

                                                      {
 
         foreach ((array)$properties as $propertyName) {
             $this->result[$propertyName] = $resultCode;
         }
 
         if ($resultCode >= 400) {
             $this->failed = true;
         }
 
     }

Here is the caller graph for this function:

Field Documentation

◆ $failed

Sabre\DAV\PropPatch::$failed = false

protected

Definition at line 52 of file PropPatch.php.

Referenced by Sabre\DAV\PropPatch\commit().

◆ $mutations

Sabre\DAV\PropPatch::$mutations

protected

Definition at line 30 of file PropPatch.php.

Referenced by Sabre\DAV\PropPatch\__construct(), and Sabre\DAV\PropPatch\getMutations().

◆ $propertyUpdateCallbacks

Sabre\DAV\PropPatch::$propertyUpdateCallbacks = []

protected

Definition at line 45 of file PropPatch.php.

◆ $result

Sabre\DAV\PropPatch::$result = []

protected

Definition at line 38 of file PropPatch.php.

Referenced by Sabre\DAV\PropPatch\doCallBackMultiProp(), Sabre\DAV\PropPatch\doCallBackSingleProp(), and Sabre\DAV\PropPatch\getResult().

The documentation for this class was generated from the following file:

libs/composer/vendor/sabre/dav/lib/DAV/PropPatch.php

Public Member Functions

Protected Attributes

Private Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ commit()

◆ doCallBackMultiProp()

◆ doCallBackSingleProp()

◆ getMutations()

◆ getRemainingMutations()

◆ getRemainingValues()

◆ getResult()

◆ handle()

◆ handleRemaining()

◆ setRemainingResultCode()

◆ setResultCode()

Field Documentation

◆ $failed

◆ $mutations

◆ $propertyUpdateCallbacks

◆ $result