API Customise type names and operation names (#143)

.travis.yml

@@ -26,9 +26,9 @@ before_script:
   - export PATH=~/.composer/vendor/bin:$PATH
   - composer validate
   - composer install --prefer-dist
-  - composer require --prefer-dist --no-update silverstripe/recipe-core:2.x-dev silverstripe/versioned:2.x-dev --prefer-dist
+  - composer require --prefer-dist --no-update silverstripe/recipe-core:1.2.x-dev silverstripe/versioned:1.2.x-dev --prefer-dist
   - composer update
-  - if [[ $DB == PGSQL ]]; then composer require silverstripe/postgresql:3.x-dev --prefer-dist; fi
+  - if [[ $DB == PGSQL ]]; then composer require silverstripe/postgresql:2.1.x-dev --prefer-dist; fi
   - if [[ $PHPCS_TEST ]]; then composer global require squizlabs/php_codesniffer:^3 --prefer-dist --no-interaction --no-progress --no-suggest -o; fi
 
 script:

README.md

@@ -47,6 +47,7 @@ composer require silverstripe/graphql
      - [Adding arbitrary queries and mutations](#adding-arbitrary-queries-and-mutations)
      - [Dealing with inheritance](#dealing-with-inheritance)
      - [Querying types that have descendants](#querying-types-that-have-descendants)
+     - [Customising the names of types and operations](#customising-the-names-of-types-and-operations)
    - [Versioned content](#versioned-content)
      - [Version-specific-operations](#version-specific-operations)
      - [Version-specific arguments](#version-specific-arguments)
@@ -1466,8 +1467,10 @@ $scaffolder
     ->type('SilverStripe\CMS\Model\RedirectorPage')
         ->addFields(['ID', 'ExternalURL', 'Content'])
         ->operation(SchemaScaffolder::READ)
+            ->setName('readRedirectors')
             ->end()
         ->operation(SchemaScaffolder::CREATE)
+            ->setName('createRedirector')
             ->end()
         ->end()
     ->type('Page')
@@ -1522,7 +1525,7 @@ input SiteTreeCreateInputType {
   # all fields from SiteTree
 }
 
-query readRedirectorPages {
+query readRedirectors {
   RedirectorPage
 }
 
@@ -1534,7 +1537,7 @@ query readSiteTrees {
   SiteTreeWithDescendants
 }
 
-mutation createRedirectorPage {
+mutation createRedirector {
   RedirectorPageCreateInputType
 }
 
@@ -1570,6 +1573,47 @@ query readSiteTrees {
   }
 }
 ```
+
+#### Customising the names of types and operations
+
+By default, the scaffolder will generate a type name for you based on the dataobject's `$table_name`
+setting and the output of its `singular_name()` method. Often times, these are poor proxies for
+a canonical name, e.g. `readMy_Really_Long_NameSpaced_BlogPosts`. To customise the type name, simply map a name to it in the `SilverStripe\GraphQL\Scaffolding\Schema`
+class.
+
+```yaml
+SilverStripe\GraphQL\Controller:
+  schema:
+    typeNames:
+      My\Really\Long\Namespaced\BlogPost: Blog
+```
+
+Note that `typeNames` is the mapping of dataobjects to the graphql types, whereas the `types`
+config is the list of type creators for non-scaffolded types, backed by php classes.
+`typeNames` is also used (and required by) scaffolding, whether via PHP or YML.
+
+Operations names are expressed using the type name of the dataobject they serve. That type name
+may be customised or computed automatically, as described above. For a deeper level of control, you can
+name the operation using the `name` property.
+
+```yaml
+...
+  operations:
+    read:
+      name: currentBlogs
+```
+
+The name of the operation has been fully customised to `currentBlogs`, returning the type `Blog`.
+
+```yaml
+...
+  operations:
+    read: true
+```
+
+Otherwise, the name of the read operation, given the `Schema` config above, will be `readBlogs`.
+
+
 ### Versioned content
 
 If the `silversrtripe/versioned` module is installed in your project (as it is with a default CMS install),

_config.php

@@ -1 +1,6 @@
 <?php
+
+// Set to 3.0.0 to show APIs marked for removal at that version
+use SilverStripe\Dev\Deprecation;
+
+Deprecation::notification_version('2.0.0', 'silverstripe/graphql');

src/Manager.php

@@ -12,6 +12,7 @@
 use GraphQL\Type\Definition\ObjectType;
 use GraphQL\Error\Error;
 use GraphQL\Type\Definition\Type;
+use SilverStripe\GraphQL\Scaffolding\StaticSchema;
 use SilverStripe\ORM\ValidationException;
 use SilverStripe\Security\Member;
 use SilverStripe\GraphQL\Scaffolding\Interfaces\ScaffoldingProvider;
@@ -68,6 +69,11 @@ class Manager
      */
     public static function createFromConfig($config)
     {
+        // Bootstrap schema class mapping from config
+        if ($config && array_key_exists('typeNames', $config)) {
+            StaticSchema::inst()->setTypeNames($config['typeNames']);
+        }
+
         /** @var Manager $manager */
         $manager = Injector::inst()->create(Manager::class);
 
@@ -257,7 +263,7 @@ public function getType($name)
     }
 
     /**
-     * @param  string  $name
+     * @param  string $name
      *
      * @return boolean
      */

src/Scaffolding/Extensions/TypeCreatorExtension.php

@@ -8,7 +8,7 @@
 use SilverStripe\ORM\DataExtension;
 use SilverStripe\Core\Injector\Injector;
 use SilverStripe\GraphQL\Scaffolding\Interfaces\TypeParserInterface;
-use SilverStripe\GraphQL\Scaffolding\Util\ScaffoldingUtil;
+use SilverStripe\GraphQL\Scaffolding\StaticSchema;
 use SilverStripe\GraphQL\Manager;
 use Exception;
 
@@ -32,7 +32,7 @@ public function createTypeParser()
             return Injector::inst()->createWithArgs(
                 TypeParserInterface::class . '.array',
                 [
-                    ScaffoldingUtil::typeName(get_class($this->owner)),
+                    StaticSchema::inst()->typeName(get_class($this->owner)),
                     $type
                 ]
             );

src/Scaffolding/Scaffolders/CRUD/Read.php

@@ -8,7 +8,7 @@
 use SilverStripe\ORM\DataList;
 use SilverStripe\GraphQL\Scaffolding\Scaffolders\UnionScaffolder;
 use SilverStripe\GraphQL\Scaffolding\Scaffolders\ListQueryScaffolder;
-use SilverStripe\GraphQL\Scaffolding\Util\ScaffoldingUtil;
+use SilverStripe\GraphQL\Scaffolding\StaticSchema;
 use SilverStripe\GraphQL\Manager;
 use SilverStripe\Core\ClassInfo;
 use Exception;
@@ -43,14 +43,14 @@ protected function getType(Manager $manager)
         array_shift($descendants);
         $union = [$this->typeName];
         foreach ($descendants as $descendant) {
-            $typeName = ScaffoldingUtil::typeNameForDataObject($descendant);
+            $typeName = StaticSchema::inst()->typeNameForDataObject($descendant);
             if ($manager->hasType($typeName)) {
                 $union[] = $typeName;
             }
         }
         if (sizeof($union) > 1) {
             return (new UnionScaffolder(
-                $this->typeName . 'WithDescendants',
+                $this->typeName.'WithDescendants',
                 $union
             ))->scaffold($manager);
         }
@@ -68,14 +68,18 @@ protected function getResults($args)
     }
 
     /**
+     *
      * @return string
      */
     protected function createOperationName()
     {
-        $typeName = $this->getDataObjectInstance()->plural_name();
-        $typeName = str_replace(' ', '', $typeName);
-        $typeName = ucfirst($typeName);
-        return 'read' . $typeName;
+        $typeName = $this->typeName();
+
+        // Ported from DataObject::plural_name()
+        if (preg_match('/[^aeiou]y$/i', $typeName)) {
+            $typeName = substr($typeName, 0, -1) . 'ie';
+        }
+        return 'read' . ucfirst($typeName . 's');
     }
 
     /**

src/Scaffolding/Scaffolders/DataObjectScaffolder.php

@@ -17,7 +17,7 @@
 use SilverStripe\GraphQL\Scaffolding\Traits\Chainable;
 use SilverStripe\GraphQL\Scaffolding\Traits\DataObjectTypeTrait;
 use SilverStripe\GraphQL\Scaffolding\Util\OperationList;
-use SilverStripe\GraphQL\Scaffolding\Util\ScaffoldingUtil;
+use SilverStripe\GraphQL\Scaffolding\StaticSchema;
 use SilverStripe\ORM\ArrayLib;
 use SilverStripe\ORM\ArrayList;
 use SilverStripe\ORM\DataList;
@@ -363,7 +363,7 @@ public function nestedQuery($fieldName, QueryScaffolder $queryScaffolder = null)
                 );
             }
 
-            $typeName = ScaffoldingUtil::typeNameForDataObject($result->dataClass());
+            $typeName = StaticSchema::inst()->typeNameForDataObject($result->dataClass());
 
             $queryScaffolder = (new ListQueryScaffolder(
                 $fieldName,
@@ -679,7 +679,7 @@ protected function createFields(Manager $manager)
 
         foreach ($this->fields as $fieldData) {
             $fieldName = $fieldData->Name;
-            if (!ScaffoldingUtil::isValidFieldName($instance, $fieldName)) {
+            if (!StaticSchema::inst()->isValidFieldName($instance, $fieldName)) {
                 throw new InvalidArgumentException(
                     sprintf(
                         'Invalid field "%s" on %s',
@@ -712,7 +712,7 @@ protected function createFields(Manager $manager)
         }
 
         foreach ($extraDataObjects as $fieldName => $className) {
-            $typeName = ScaffoldingUtil::typeNameForDataObject($className);
+            $typeName = StaticSchema::inst()->typeNameForDataObject($className);
             $description = $this->getFieldDescription($fieldName);
             $fieldMap[$fieldName] = [
                 'type' => $manager->getType($typeName),

src/Scaffolding/Scaffolders/OperationScaffolder.php

@@ -226,6 +226,17 @@ public function getName()
         return $this->operationName;
     }
 
+    /**
+     * @param $name
+     * @return $this
+     */
+    public function setName($name)
+    {
+        $this->operationName = $name;
+
+        return $this;
+    }
+
     /**
      * @return ArrayList
      */
@@ -326,6 +337,9 @@ public function applyConfig(array $config)
         if (isset($config['resolver'])) {
             $this->setResolver($config['resolver']);
         }
+        if (isset($config['name'])) {
+            $this->setName($config['name']);
+        }
 
         return $this;
     }

src/Scaffolding/Scaffolders/SchemaScaffolder.php

@@ -12,7 +12,7 @@
 use SilverStripe\GraphQL\Scaffolding\Interfaces\ManagerMutatorInterface;
 use SilverStripe\GraphQL\Scaffolding\Interfaces\ResolverInterface;
 use SilverStripe\GraphQL\Scaffolding\Util\OperationList;
-use SilverStripe\GraphQL\Scaffolding\Util\ScaffoldingUtil;
+use SilverStripe\GraphQL\Scaffolding\StaticSchema;
 use SilverStripe\ORM\ArrayLib;
 use SilverStripe\View\ViewableData;
 
@@ -161,7 +161,7 @@ public function query($name, $class, $resolver = null)
 
         $operationScaffold = (new ListQueryScaffolder(
             $name,
-            ScaffoldingUtil::typeNameForDataObject($class),
+            StaticSchema::inst()->typeNameForDataObject($class),
             $resolver
         ))->setChainableParent($this);
 
@@ -188,7 +188,7 @@ public function mutation($name, $class, $resolver = null)
 
         $operationScaffold = (new MutationScaffolder(
             $name,
-            ScaffoldingUtil::typeNameForDataObject($class),
+            StaticSchema::inst()->typeNameForDataObject($class),
             $resolver
         ))->setChainableParent($this);
 
@@ -377,7 +377,7 @@ protected function registerPeripheralTypes(Manager $manager)
                 $ancestorType = $this->type($class);
                 $inst = $ancestorType->getDataObjectInstance();
                 foreach ($exposedFields as $field) {
-                    if (ScaffoldingUtil::isValidFieldName($inst, $field->Name)) {
+                    if (StaticSchema::inst()->isValidFieldName($inst, $field->Name)) {
                         $ancestorType->addField($field->Name, $field->Description);
                     }
                 }

src/Scaffolding/Scaffolders/UnionScaffolder.php

@@ -7,7 +7,7 @@
 use SilverStripe\Core\ClassInfo;
 use SilverStripe\GraphQL\Manager;
 use SilverStripe\GraphQL\Scaffolding\Interfaces\ScaffolderInterface;
-use SilverStripe\GraphQL\Scaffolding\Util\ScaffoldingUtil;
+use SilverStripe\GraphQL\Scaffolding\StaticSchema;
 use SilverStripe\ORM\DataObject;
 
 class UnionScaffolder implements ScaffolderInterface
@@ -24,7 +24,7 @@ class UnionScaffolder implements ScaffolderInterface
     protected $types = [];
 
     /**
-     * @param string $baseType
+     * @param string $name
      * @param array  $types
      */
     public function __construct($name, $types = [])
@@ -55,17 +55,17 @@ public function scaffold(Manager $manager)
                 $ancestry = array_reverse(ClassInfo::ancestry($obj));
                 foreach ($ancestry as $class) {
                     if ($class === DataObject::class) {
-                        throw new Exception(sprintf(
-                            'There is no type defined for %s, and none of its ancestors are defined.',
-                            get_class($obj)
-                        ));
+                        break;
                     }
-
-                    $typeName = ScaffoldingUtil::typeNameForDataObject($class);
+                    $typeName = StaticSchema::inst()->typeNameForDataObject($class);
                     if ($manager->hasType($typeName)) {
                         return $manager->getType($typeName);
                     }
                 }
+                throw new Exception(sprintf(
+                    'There is no type defined for %s, and none of its ancestors are defined.',
+                    get_class($obj)
+                ));
             }
         ]);
     }