From 6df1bb4e5e1185e1e14791bd8c7912973f5065e9 Mon Sep 17 00:00:00 2001 From: Aaron Carlino Date: Thu, 23 Dec 2021 13:40:53 +1300 Subject: [PATCH] DOCS: Docs for various new graphql features --- .../03_building_the_schema.md | 7 ++++++ .../01_dataobject_model_type.md | 19 ++++++++++++++++ .../19_GraphQL/07_tips_and_tricks.md | 22 +++++++++++++++++++ 3 files changed, 48 insertions(+) diff --git a/docs/en/02_Developer_Guides/19_GraphQL/01_getting_started/03_building_the_schema.md b/docs/en/02_Developer_Guides/19_GraphQL/01_getting_started/03_building_the_schema.md index acd11ef68f2..9ccd056a9a2 100644 --- a/docs/en/02_Developer_Guides/19_GraphQL/01_getting_started/03_building_the_schema.md +++ b/docs/en/02_Developer_Guides/19_GraphQL/01_getting_started/03_building_the_schema.md @@ -41,6 +41,13 @@ Keep in mind that many of your changes will be in YAML, which also requires a fl If you do not provide a `schema` parameter, the task will build all schemas. [/info] +#### Controlling verbosity + +You can set the verbosity of the output by using `verbosity=`. +Available values are the constants found in `SilverStripe\GraphQL\Schema\Logger`, e.g. `INFO`, `DEBUG`, `WARNING`. +By default, the verbosity is set to `INFO`. + + ### Building on dev/build By default, all schemas will be built as a side-effect of `dev/build`. To disable this, change diff --git a/docs/en/02_Developer_Guides/19_GraphQL/02_working_with_dataobjects/01_dataobject_model_type.md b/docs/en/02_Developer_Guides/19_GraphQL/02_working_with_dataobjects/01_dataobject_model_type.md index 1f9dcc38507..042c41f3ef5 100644 --- a/docs/en/02_Developer_Guides/19_GraphQL/02_working_with_dataobjects/01_dataobject_model_type.md +++ b/docs/en/02_Developer_Guides/19_GraphQL/02_working_with_dataobjects/01_dataobject_model_type.md @@ -279,6 +279,25 @@ Given the brevity of these type names, it's not inconceivable that you could run collisions, particularly if you use feature-based namespacing. Fortunately, there are hooks you have available to help influence the typename. +#### Explicit type mapping + +You can explicitly provide type name for a given class using the `typeMapping` setting in your schema config. + +**app/_graphql/config.yml** +```yaml +typeMapping: + MyProject\MyApp\Page: SpecialPage +``` + +It may be necessary to use `typeMapping` in projects that have a lot of similar class names in different namespaces, which will cause a collision +when the type name is derived from the class name. The most case for this +is the `Page` class, which is both at the root namespace and often in your +app namespace, e.g. `MyApp\Models\Page`. + + + + + #### The type formatter The `type_formatter` is a callable that can be set on the `DataObjectModel` config. It takes diff --git a/docs/en/02_Developer_Guides/19_GraphQL/07_tips_and_tricks.md b/docs/en/02_Developer_Guides/19_GraphQL/07_tips_and_tricks.md index 29dcd71ef72..57cf1a77fd5 100644 --- a/docs/en/02_Developer_Guides/19_GraphQL/07_tips_and_tricks.md +++ b/docs/en/02_Developer_Guides/19_GraphQL/07_tips_and_tricks.md @@ -13,6 +13,28 @@ Docs for the current stable version (3.x) can be found [here](https://github.com/silverstripe/silverstripe-graphql/tree/3) [/alert] + +## Debugging the generated code + +By default, the generated PHP code is put into obfuscated classnames and filenames to prevent poisoning the search +tools within IDEs. Without this, you can search for something like "Page" in your IDE and get both a generated GraphQL type (probably not what you want) and a DataObject (more likely what you want) in the results and have no easy way of differentiating between the two. + +When debugging, however, it's much easier if these classnames are human-readable. To turn on debug mode, add `DEBUG_SCHEMA=1` to your environment file and the classnames and filenames in the generated code directory will match their type names. + +[warning] +Take care not to use `DEBUG_SCHEMA=1` as an inline environment variable to your build command, e.g. `DEBUG_SCHEMA=1 vendor/bin/sake dev/graphql/build` because any activity that happens at run time, e.g. querying the schema will fail, since the environment variable is no longer set. +[/warning] + +In live mode, full obfuscation kicks in and the filenames become unreadable. You can only determine the type they map +to by looking at the generated classes and finding the `// @type:` inline comment, e.g. `// @type:Page`. + +This obfuscation is handled by the `NameObfuscator` interface. See the `config.yml` file in the GraphQL module for +the various implementations, which include: + +* `NaiveNameObfuscator`: Filename/Classname === Type name +* `HybridNameObfuscator`: Filename/Classname is a mix of the typename and a hash (default). +* `HashNameObfuscator`: Filename/Classname is a md5 hash of the type name (non-dev only). + ## Getting the type name for a model class Often times, you'll need to know the name of the type given a class name. There's a bit of context to this.