From e3c6d5ffe00bbe906f066f13c21d404b46075442 Mon Sep 17 00:00:00 2001 From: Coleman Watts Date: Mon, 3 Feb 2020 18:05:38 -0500 Subject: [PATCH] APIv4 - Pluralize entity name in docblocks --- CRM/Utils/String.php | 19 +++++++++++++++++++ Civi/Api4/Action/Entity/Get.php | 2 +- Civi/Api4/Action/GetActions.php | 2 +- Civi/Api4/Generic/AbstractAction.php | 8 ++++---- Civi/Api4/Generic/AbstractBatchAction.php | 2 +- Civi/Api4/Generic/AbstractGetAction.php | 2 +- Civi/Api4/Generic/AbstractQueryAction.php | 4 ++-- Civi/Api4/Generic/AbstractSaveAction.php | 6 +++--- Civi/Api4/Generic/AbstractUpdateAction.php | 2 +- Civi/Api4/Generic/BasicBatchAction.php | 4 ++-- Civi/Api4/Generic/BasicCreateAction.php | 2 +- Civi/Api4/Generic/BasicGetAction.php | 2 +- Civi/Api4/Generic/BasicReplaceAction.php | 16 ++++++++-------- Civi/Api4/Generic/BasicSaveAction.php | 2 +- Civi/Api4/Generic/DAOCreateAction.php | 2 +- Civi/Api4/Generic/DAODeleteAction.php | 4 ++-- Civi/Api4/Generic/DAOGetAction.php | 2 +- Civi/Api4/Generic/DAOSaveAction.php | 2 +- Civi/Api4/Utils/ReflectionUtils.php | 5 +++-- .../api/v4/Utils/ReflectionUtilsTest.php | 2 +- 20 files changed, 55 insertions(+), 35 deletions(-) diff --git a/CRM/Utils/String.php b/CRM/Utils/String.php index 9277ca59cb..1c878580af 100644 --- a/CRM/Utils/String.php +++ b/CRM/Utils/String.php @@ -952,4 +952,23 @@ class CRM_Utils_String { } } + /** + * Returns the plural form of an English word. + * + * @param string $str + * @return string + */ + public static function pluralize($str) { + switch (substr($str, -1)) { + case 's': + return $str . 'es'; + + case 'y': + return substr($str, 0, -1) . 'ies'; + + default: + return $str . 's'; + } + } + } diff --git a/Civi/Api4/Action/Entity/Get.php b/Civi/Api4/Action/Entity/Get.php index b8e0763ee2..2b42ea2375 100644 --- a/Civi/Api4/Action/Entity/Get.php +++ b/Civi/Api4/Action/Entity/Get.php @@ -132,7 +132,7 @@ class Get extends \Civi\Api4\Generic\BasicGetAction { */ private function addDocs(&$entity) { $reflection = new \ReflectionClass("\\Civi\\Api4\\" . $entity['name']); - $entity += ReflectionUtils::getCodeDocs($reflection, NULL, ['$ENTITY' => $entity['name']]); + $entity += ReflectionUtils::getCodeDocs($reflection, NULL, ['entity' => $entity['name']]); unset($entity['package'], $entity['method']); } diff --git a/Civi/Api4/Action/GetActions.php b/Civi/Api4/Action/GetActions.php index 0ce201b797..b16fb0a285 100644 --- a/Civi/Api4/Action/GetActions.php +++ b/Civi/Api4/Action/GetActions.php @@ -88,7 +88,7 @@ class GetActions extends BasicGetAction { if (is_object($action)) { $this->_actions[$actionName] = ['name' => $actionName]; if ($this->_isFieldSelected('description', 'comment', 'see')) { - $vars = ['$ENTITY' => $this->getEntityName(), '$ACTION' => $actionName]; + $vars = ['entity' => $this->getEntityName(), 'action' => $actionName]; // Docblock from action class $actionDocs = ReflectionUtils::getCodeDocs($action->reflect(), NULL, $vars); unset($actionDocs['method']); diff --git a/Civi/Api4/Generic/AbstractAction.php b/Civi/Api4/Generic/AbstractAction.php index 5138c1c87a..531f11aace 100644 --- a/Civi/Api4/Generic/AbstractAction.php +++ b/Civi/Api4/Generic/AbstractAction.php @@ -271,13 +271,13 @@ abstract class AbstractAction implements \ArrayAccess { if (!isset($this->_paramInfo)) { $defaults = $this->getParamDefaults(); $vars = [ - '$ENTITY' => $this->getEntityName(), - '$ACTION' => $this->getActionName(), + 'entity' => $this->getEntityName(), + 'action' => $this->getActionName(), ]; // For actions like "getFields" and "getActions" they are not getting the entity itself. // So generic docs will make more sense like this: - if (substr($vars['$ACTION'], 0, 3) === 'get' && substr($vars['$ACTION'], -1) === 's') { - $vars['$ENTITY'] = lcfirst(substr($vars['$ACTION'], 3, -1)); + if (substr($vars['action'], 0, 3) === 'get' && substr($vars['action'], -1) === 's') { + $vars['entity'] = lcfirst(substr($vars['action'], 3, -1)); } foreach ($this->reflect()->getProperties(\ReflectionProperty::IS_PROTECTED) as $property) { $name = $property->getName(); diff --git a/Civi/Api4/Generic/AbstractBatchAction.php b/Civi/Api4/Generic/AbstractBatchAction.php index 89fe786eea..4945b43291 100644 --- a/Civi/Api4/Generic/AbstractBatchAction.php +++ b/Civi/Api4/Generic/AbstractBatchAction.php @@ -31,7 +31,7 @@ namespace Civi\Api4\Generic; abstract class AbstractBatchAction extends AbstractQueryAction { /** - * Criteria for selecting $ENTITYs to process. + * Criteria for selecting $ENTITIES to process. * * @var array * @required diff --git a/Civi/Api4/Generic/AbstractGetAction.php b/Civi/Api4/Generic/AbstractGetAction.php index 0f4f37e395..e9f892c2af 100644 --- a/Civi/Api4/Generic/AbstractGetAction.php +++ b/Civi/Api4/Generic/AbstractGetAction.php @@ -39,7 +39,7 @@ abstract class AbstractGetAction extends AbstractQueryAction { * Use the * wildcard by itself to select all available fields, or use it to match similarly-named fields. * E.g. `is_*` will match fields named is_primary, is_active, etc. * - * Set to `["row_count"]` to return only the number of $ENTITYs found. + * Set to `["row_count"]` to return only the number of $ENTITIES found. * * @var array */ diff --git a/Civi/Api4/Generic/AbstractQueryAction.php b/Civi/Api4/Generic/AbstractQueryAction.php index 74aa495b82..e58ab26659 100644 --- a/Civi/Api4/Generic/AbstractQueryAction.php +++ b/Civi/Api4/Generic/AbstractQueryAction.php @@ -38,7 +38,7 @@ namespace Civi\Api4\Generic; abstract class AbstractQueryAction extends AbstractAction { /** - * Criteria for selecting $ENTITYs. + * Criteria for selecting $ENTITIES. * * ```php * $example->addWhere('contact_type', 'IN', ['Individual', 'Household']) @@ -60,7 +60,7 @@ abstract class AbstractQueryAction extends AbstractAction { protected $orderBy = []; /** - * Maximum number of $ENTITYs to return. + * Maximum number of $ENTITIES to return. * * Defaults to unlimited. * diff --git a/Civi/Api4/Generic/AbstractSaveAction.php b/Civi/Api4/Generic/AbstractSaveAction.php index a644cc459c..749184ed8d 100644 --- a/Civi/Api4/Generic/AbstractSaveAction.php +++ b/Civi/Api4/Generic/AbstractSaveAction.php @@ -36,7 +36,7 @@ namespace Civi\Api4\Generic; abstract class AbstractSaveAction extends AbstractAction { /** - * Array of $ENTITYs to save. + * Array of $ENTITIES to save. * * Should be in the same format as returned by `Get`. * @@ -50,14 +50,14 @@ abstract class AbstractSaveAction extends AbstractAction { * * These defaults will be merged into every $ENTITY in `records` before saving. * Values set in `records` will override these defaults if set in both places, - * but updating existing $ENTITYs will overwrite current values with these defaults. + * but updating existing $ENTITIES will overwrite current values with these defaults. * * @var array */ protected $defaults = []; /** - * Reload $ENTITYs after saving. + * Reload $ENTITIES after saving. * * By default this action typically returns partial records containing only the fields * that were updated. Set `reload` to `true` to do an additional lookup after saving diff --git a/Civi/Api4/Generic/AbstractUpdateAction.php b/Civi/Api4/Generic/AbstractUpdateAction.php index 6c6ca176cb..93940e1976 100644 --- a/Civi/Api4/Generic/AbstractUpdateAction.php +++ b/Civi/Api4/Generic/AbstractUpdateAction.php @@ -42,7 +42,7 @@ abstract class AbstractUpdateAction extends AbstractBatchAction { protected $values = []; /** - * Reload $ENTITYs after saving. + * Reload $ENTITIES after saving. * * Setting to `true` will load complete records and return them as the api result. * If `false` the api usually returns only the fields specified to be updated. diff --git a/Civi/Api4/Generic/BasicBatchAction.php b/Civi/Api4/Generic/BasicBatchAction.php index 860e4273a5..cf86203a9e 100644 --- a/Civi/Api4/Generic/BasicBatchAction.php +++ b/Civi/Api4/Generic/BasicBatchAction.php @@ -24,9 +24,9 @@ namespace Civi\Api4\Generic; use Civi\API\Exception\NotImplementedException; /** - * $ACTION one or more $ENTITYs. + * $ACTION one or more $ENTITIES. * - * $ENTITYs are selected based on criteria specified in `where` parameter (required). + * $ENTITIES are selected based on criteria specified in `where` parameter (required). * * @package Civi\Api4\Generic */ diff --git a/Civi/Api4/Generic/BasicCreateAction.php b/Civi/Api4/Generic/BasicCreateAction.php index e06c869423..66f4e1b50f 100644 --- a/Civi/Api4/Generic/BasicCreateAction.php +++ b/Civi/Api4/Generic/BasicCreateAction.php @@ -27,7 +27,7 @@ use Civi\API\Exception\NotImplementedException; * Create a new $ENTITY from supplied values. * * This action will create 1 new $ENTITY. - * It cannot be used to update existing $ENTITYs; use the `Update` or `Replace` actions for that. + * It cannot be used to update existing $ENTITIES; use the `Update` or `Replace` actions for that. */ class BasicCreateAction extends AbstractCreateAction { diff --git a/Civi/Api4/Generic/BasicGetAction.php b/Civi/Api4/Generic/BasicGetAction.php index 0a9e047daa..22278c973e 100644 --- a/Civi/Api4/Generic/BasicGetAction.php +++ b/Civi/Api4/Generic/BasicGetAction.php @@ -24,7 +24,7 @@ namespace Civi\Api4\Generic; use Civi\API\Exception\NotImplementedException; /** - * Retrieve $ENTITYs based on criteria specified in the `where` parameter. + * Retrieve $ENTITIES based on criteria specified in the `where` parameter. * * Use the `select` param to determine which fields are returned, defaults to `[*]`. */ diff --git a/Civi/Api4/Generic/BasicReplaceAction.php b/Civi/Api4/Generic/BasicReplaceAction.php index 09f645a750..b8e20285cd 100644 --- a/Civi/Api4/Generic/BasicReplaceAction.php +++ b/Civi/Api4/Generic/BasicReplaceAction.php @@ -24,14 +24,14 @@ namespace Civi\Api4\Generic; use Civi\Api4\Utils\ActionUtil; /** - * Replaces an existing set of $ENTITYs with a new one. + * Replaces an existing set of $ENTITIES with a new one. * - * This will select a group of existing $ENTITYs based on the `where` parameter. - * Each will be compared with the $ENTITYs passed in as `records`: + * This will select a group of existing $ENTITIES based on the `where` parameter. + * Each will be compared with the $ENTITIES passed in as `records`: * - * - $ENTITYs in `records` that don't already exist will be created. - * - Existing $ENTITYs that are included in `records` will be updated. - * - Existing $ENTITYs that are omitted from `records` will be deleted. + * - $ENTITIES in `records` that don't already exist will be created. + * - Existing $ENTITIES that are included in `records` will be updated. + * - Existing $ENTITIES that are omitted from `records` will be deleted. * * @method $this setRecords(array $records) Set array of records. * @method array getRecords() @@ -57,7 +57,7 @@ class BasicReplaceAction extends AbstractBatchAction { * * These defaults will be merged into every $ENTITY in `records` before saving. * Values set in `records` will override these defaults if set in both places, - * but updating existing $ENTITYs will overwrite current values with these defaults. + * but updating existing $ENTITIES will overwrite current values with these defaults. * * **Note:** Values from the `where` clause that use the `=` operator are _also_ treated as default values; * those do not need to be repeated here. @@ -67,7 +67,7 @@ class BasicReplaceAction extends AbstractBatchAction { protected $defaults = []; /** - * Reload $ENTITYs after saving. + * Reload $ENTITIES after saving. * * By default this action typically returns partial records containing only the fields * that were updated. Set `reload` to `true` to do an additional lookup after saving diff --git a/Civi/Api4/Generic/BasicSaveAction.php b/Civi/Api4/Generic/BasicSaveAction.php index ba4c1a12df..b5c998af56 100644 --- a/Civi/Api4/Generic/BasicSaveAction.php +++ b/Civi/Api4/Generic/BasicSaveAction.php @@ -25,7 +25,7 @@ use Civi\API\Exception\NotImplementedException; use Civi\Api4\Utils\ActionUtil; /** - * $ACTION one or more $ENTITYs. + * $ACTION one or more $ENTITIES. * * If saving more than one new $ENTITY with similar values, use the `defaults` parameter. * diff --git a/Civi/Api4/Generic/DAOCreateAction.php b/Civi/Api4/Generic/DAOCreateAction.php index 59436c0d99..c90b81116d 100644 --- a/Civi/Api4/Generic/DAOCreateAction.php +++ b/Civi/Api4/Generic/DAOCreateAction.php @@ -25,7 +25,7 @@ namespace Civi\Api4\Generic; * Create a new $ENTITY from supplied values. * * This action will create 1 new $ENTITY. - * It cannot be used to update existing $ENTITYs; use the `Update` or `Replace` actions for that. + * It cannot be used to update existing $ENTITIES; use the `Update` or `Replace` actions for that. */ class DAOCreateAction extends AbstractCreateAction { use Traits\DAOActionTrait; diff --git a/Civi/Api4/Generic/DAODeleteAction.php b/Civi/Api4/Generic/DAODeleteAction.php index 83b39a38bf..3e0135f899 100644 --- a/Civi/Api4/Generic/DAODeleteAction.php +++ b/Civi/Api4/Generic/DAODeleteAction.php @@ -22,9 +22,9 @@ namespace Civi\Api4\Generic; /** - * Delete one or more $ENTITYs. + * Delete one or more $ENTITIES. * - * $ENTITYs are deleted based on criteria specified in `where` parameter (required). + * $ENTITIES are deleted based on criteria specified in `where` parameter (required). */ class DAODeleteAction extends AbstractBatchAction { use Traits\DAOActionTrait; diff --git a/Civi/Api4/Generic/DAOGetAction.php b/Civi/Api4/Generic/DAOGetAction.php index da97a68d40..c7472969f4 100644 --- a/Civi/Api4/Generic/DAOGetAction.php +++ b/Civi/Api4/Generic/DAOGetAction.php @@ -22,7 +22,7 @@ namespace Civi\Api4\Generic; /** - * Retrieve $ENTITYs based on criteria specified in the `where` parameter. + * Retrieve $ENTITIES based on criteria specified in the `where` parameter. * * Use the `select` param to determine which fields are returned, defaults to `[*]`. * diff --git a/Civi/Api4/Generic/DAOSaveAction.php b/Civi/Api4/Generic/DAOSaveAction.php index ab4888a38a..954ecae5ba 100644 --- a/Civi/Api4/Generic/DAOSaveAction.php +++ b/Civi/Api4/Generic/DAOSaveAction.php @@ -22,7 +22,7 @@ namespace Civi\Api4\Generic; /** - * Create or update one or more $ENTITYs. + * Create or update one or more $ENTITIES. * * If creating more than one $ENTITY with similar values, use the `defaults` param. * diff --git a/Civi/Api4/Utils/ReflectionUtils.php b/Civi/Api4/Utils/ReflectionUtils.php index 4ff7d9775e..0733b20f89 100644 --- a/Civi/Api4/Utils/ReflectionUtils.php +++ b/Civi/Api4/Utils/ReflectionUtils.php @@ -26,8 +26,9 @@ class ReflectionUtils { */ public static function getCodeDocs($reflection, $type = NULL, $vars = []) { $comment = $reflection->getDocComment(); - if ($vars) { - $comment = str_replace(array_keys($vars), array_values($vars), $comment); + foreach ($vars as $key => $val) { + $comment = str_replace('$' . strtoupper(\CRM_Utils_String::pluralize($key)), \CRM_Utils_String::pluralize($val), $comment); + $comment = str_replace('$' . strtoupper($key), $val, $comment); } $docs = self::parseDocBlock($comment); diff --git a/tests/phpunit/api/v4/Utils/ReflectionUtilsTest.php b/tests/phpunit/api/v4/Utils/ReflectionUtilsTest.php index fb3b644585..fc962ac5ed 100644 --- a/tests/phpunit/api/v4/Utils/ReflectionUtilsTest.php +++ b/tests/phpunit/api/v4/Utils/ReflectionUtilsTest.php @@ -36,7 +36,7 @@ class ReflectionUtilsTest extends UnitTestCase { public function testGetDocBlockForClass() { $grandChild = new MockV4ReflectionGrandchild(); $reflection = new \ReflectionClass($grandChild); - $doc = ReflectionUtils::getCodeDocs($reflection, NULL, ['$ENTITY' => "Test"]); + $doc = ReflectionUtils::getCodeDocs($reflection, NULL, ['entity' => "Test"]); $this->assertEquals(TRUE, $doc['internal']); $this->assertEquals('Grandchild class for Test, with a 2-line description!', $doc['description']); -- 2.25.1