Added slug to documentation dsl function definitions (#1194)

flow-php · Aug 16, 2024 · fdb67e9 · fdb67e9
1 parent a7d650e
commit fdb67e9
Show file tree

Hide file tree

Showing 27 changed files with 367 additions and 278 deletions.
diff --git a/composer.json b/composer.json
@@ -40,6 +40,7 @@
     },
     "require-dev": {
         "aeon-php/calendar": "^1.0",
+        "cocur/slugify": "^4.5",
         "fakerphp/faker": "^1.23",
         "fig/log-test": "^1.1",
         "nikic/php-parser": "^4.18",

diff --git a/composer.lock b/composer.lock
diff --git a/src/adapter/etl-adapter-chartjs/src/Flow/ETL/Adapter/ChartJS/functions.php b/src/adapter/etl-adapter-chartjs/src/Flow/ETL/Adapter/ChartJS/functions.php
@@ -5,29 +5,29 @@
 namespace Flow\ETL\Adapter\ChartJS;
 
 use Flow\ETL\Adapter\ChartJS\Chart\{BarChart, LineChart, PieChart};
-use Flow\ETL\Attribute\{DSL, Module, Type};
+use Flow\ETL\Attribute\{DocumentationDSL, Module, Type};
 use Flow\ETL\Row\{EntryReference, References};
 use Flow\Filesystem\Path;
 
-#[DSL(module: Module::CHARTJS, type: Type::HELPER)]
+#[DocumentationDSL(module: Module::CHARTJS, type: Type::HELPER)]
 function bar_chart(EntryReference $label, References $datasets) : BarChart
 {
     return new BarChart($label, $datasets);
 }
 
-#[DSL(module: Module::CHARTJS, type: Type::HELPER)]
+#[DocumentationDSL(module: Module::CHARTJS, type: Type::HELPER)]
 function line_chart(EntryReference $label, References $datasets) : LineChart
 {
     return new LineChart($label, $datasets);
 }
 
-#[DSL(module: Module::CHARTJS, type: Type::HELPER)]
+#[DocumentationDSL(module: Module::CHARTJS, type: Type::HELPER)]
 function pie_chart(EntryReference $label, References $datasets) : PieChart
 {
     return new PieChart($label, $datasets);
 }
 
-#[DSL(module: Module::CHARTJS, type: Type::LOADER)]
+#[DocumentationDSL(module: Module::CHARTJS, type: Type::LOADER)]
 function to_chartjs_file(Chart $type, Path|string|null $output = null, Path|string|null $template = null) : ChartJSLoader
 {
     if (\is_string($output)) {
@@ -45,7 +45,7 @@ function to_chartjs_file(Chart $type, Path|string|null $output = null, Path|stri
     return new ChartJSLoader($type, output: $output, template: $template);
 }
 
-#[DSL(module: Module::CHARTJS, type: Type::LOADER)]
+#[DocumentationDSL(module: Module::CHARTJS, type: Type::LOADER)]
 function to_chartjs_var(Chart $type, array &$output) : ChartJSLoader
 {
     /** @psalm-suppress ReferenceConstraintViolation */

diff --git a/src/adapter/etl-adapter-csv/src/Flow/ETL/Adapter/CSV/functions.php b/src/adapter/etl-adapter-csv/src/Flow/ETL/Adapter/CSV/functions.php
@@ -7,13 +7,13 @@
 use function Flow\ETL\DSL\from_all;
 use Flow\ETL\Adapter\CSV\Detector\{Option, Options};
 use Flow\ETL\Row\Schema;
-use Flow\ETL\{Attribute\DSL, Attribute\Module, Attribute\Type as DSLType, Extractor, Loader};
+use Flow\ETL\{Attribute\DocumentationDSL, Attribute\Module, Attribute\Type as DSLType, Extractor, Loader};
 use Flow\Filesystem\{Path, SourceStream};
 
 /**
  * @param int<1, max> $characters_read_in_line
  */
-#[DSL(module: Module::CSV, type: DSLType::EXTRACTOR)]
+#[DocumentationDSL(module: Module::CSV, type: DSLType::EXTRACTOR)]
 function from_csv(
     string|Path|array $path,
     bool $with_header = true,
@@ -55,7 +55,7 @@ function from_csv(
     );
 }
 
-#[DSL(module: Module::CSV, type: DSLType::LOADER)]
+#[DocumentationDSL(module: Module::CSV, type: DSLType::LOADER)]
 function to_csv(
     string|Path $uri,
     bool $with_header = true,
@@ -82,7 +82,7 @@ function to_csv(
  * @param null|Option $fallback - fallback option to use when no best option can be detected, default is Option(',', '"', '\\')
  * @param null|Options $options - options to use for detection, default is Options::all()
  */
-#[DSL(module: Module::CSV, type: DSLType::HELPER)]
+#[DocumentationDSL(module: Module::CSV, type: DSLType::HELPER)]
 function csv_detect_separator(SourceStream $stream, int $lines = 5, ?Option $fallback = new Option(',', '"', '\\'), ?Options $options = null) : Option
 {
     return (new CSVDetector($stream, $fallback, $options))->detect($lines);

diff --git a/src/adapter/etl-adapter-doctrine/src/Flow/ETL/Adapter/Doctrine/functions.php b/src/adapter/etl-adapter-doctrine/src/Flow/ETL/Adapter/Doctrine/functions.php
@@ -8,7 +8,7 @@
 use Doctrine\DBAL\Types\Type as DbalType;
 use Doctrine\DBAL\{ArrayParameterType as DbalArrayType, Connection, ParameterType as DbalParameterType};
 use Flow\ETL\Exception\InvalidArgumentException;
-use Flow\ETL\{Attribute\DSL,
+use Flow\ETL\{Attribute\DocumentationDSL,
     Attribute\Module,
     Attribute\Type as DSLType
 };
@@ -18,7 +18,7 @@
  * @param string $query
  * @param QueryParameter ...$parameters
  */
-#[DSL(module: Module::DOCTRINE, type: DSLType::HELPER)]
+#[DocumentationDSL(module: Module::DOCTRINE, type: DSLType::HELPER)]
 function dbal_dataframe_factory(
     array|Connection $connection,
     string $query,
@@ -38,7 +38,7 @@ function dbal_dataframe_factory(
  *
  * @throws InvalidArgumentException
  */
-#[DSL(module: Module::DOCTRINE, type: DSLType::EXTRACTOR)]
+#[DocumentationDSL(module: Module::DOCTRINE, type: DSLType::EXTRACTOR)]
 function from_dbal_limit_offset(
     Connection $connection,
     string|Table $table,
@@ -60,7 +60,7 @@ function from_dbal_limit_offset(
  * @param int $page_size
  * @param null|int $maximum
  */
-#[DSL(module: Module::DOCTRINE, type: DSLType::EXTRACTOR)]
+#[DocumentationDSL(module: Module::DOCTRINE, type: DSLType::EXTRACTOR)]
 function from_dbal_limit_offset_qb(
     Connection $connection,
     QueryBuilder $queryBuilder,
@@ -79,7 +79,7 @@ function from_dbal_limit_offset_qb(
  * @param null|ParametersSet $parameters_set - each one parameters array will be evaluated as new query
  * @param array<int|string, DbalArrayType|DbalParameterType|DbalType|int|string> $types
  */
-#[DSL(module: Module::DOCTRINE, type: DSLType::EXTRACTOR)]
+#[DocumentationDSL(module: Module::DOCTRINE, type: DSLType::EXTRACTOR)]
 function dbal_from_queries(
     Connection $connection,
     string $query,
@@ -98,7 +98,7 @@ function dbal_from_queries(
  * @param array<string, mixed>|list<mixed> $parameters
  * @param array<int|string, DbalArrayType|DbalParameterType|DbalType|int|string> $types
  */
-#[DSL(module: Module::DOCTRINE, type: DSLType::EXTRACTOR)]
+#[DocumentationDSL(module: Module::DOCTRINE, type: DSLType::EXTRACTOR)]
 function dbal_from_query(
     Connection $connection,
     string $query,
@@ -127,7 +127,7 @@ function dbal_from_query(
  *
  * @throws InvalidArgumentException
  */
-#[DSL(module: Module::DOCTRINE, type: DSLType::LOADER)]
+#[DocumentationDSL(module: Module::DOCTRINE, type: DSLType::LOADER)]
 function to_dbal_table_insert(
     array|Connection $connection,
     string $table,
@@ -152,7 +152,7 @@ function to_dbal_table_insert(
  *
  * @throws InvalidArgumentException
  */
-#[DSL(module: Module::DOCTRINE, type: DSLType::LOADER)]
+#[DocumentationDSL(module: Module::DOCTRINE, type: DSLType::LOADER)]
 function to_dbal_table_update(
     array|Connection $connection,
     string $table,

diff --git a/src/adapter/etl-adapter-elasticsearch/src/Flow/ETL/Adapter/Elasticsearch/functions.php b/src/adapter/etl-adapter-elasticsearch/src/Flow/ETL/Adapter/Elasticsearch/functions.php
@@ -5,7 +5,7 @@
 namespace Flow\ETL\Adapter\Elasticsearch;
 
 use Flow\ETL\Adapter\Elasticsearch\ElasticsearchPHP\{DocumentDataSource, ElasticsearchExtractor, ElasticsearchLoader, HitsIntoRowsTransformer};
-use Flow\ETL\Attribute\{DSL, Module, Type};
+use Flow\ETL\Attribute\{DocumentationDSL, Module, Type};
 
 /**
  * https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-bulk.html.
@@ -27,7 +27,7 @@
  * @param IdFactory $id_factory
  * @param array<mixed> $parameters - https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-bulk.html
  */
-#[DSL(module: Module::ELASTICSEARCH, type: Type::LOADER)]
+#[DocumentationDSL(module: Module::ELASTICSEARCH, type: Type::LOADER)]
 function to_es_bulk_index(
     array $config,
     string $index,
@@ -57,7 +57,7 @@ function to_es_bulk_index(
  * @param IdFactory $id_factory
  * @param array<mixed> $parameters - https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-bulk.html
  */
-#[DSL(module: Module::ELASTICSEARCH, type: Type::LOADER)]
+#[DocumentationDSL(module: Module::ELASTICSEARCH, type: Type::LOADER)]
 function to_es_bulk_update(
     array $config,
     string $index,
@@ -72,7 +72,7 @@ function to_es_bulk_update(
  *
  * @return HitsIntoRowsTransformer
  */
-#[DSL(module: Module::ELASTICSEARCH, type: Type::HELPER)]
+#[DocumentationDSL(module: Module::ELASTICSEARCH, type: Type::HELPER)]
 function es_hits_to_rows(DocumentDataSource $source = DocumentDataSource::source) : HitsIntoRowsTransformer
 {
     return new HitsIntoRowsTransformer($source);
@@ -100,7 +100,7 @@ function es_hits_to_rows(DocumentDataSource $source = DocumentDataSource::source
  * @param array<mixed> $params - https://www.elastic.co/guide/en/elasticsearch/reference/master/search-search.html
  * @param ?array<mixed> $pit_params - when used extractor will create point in time to stabilize search results. Point in time is automatically closed when last element is extracted. https://www.elastic.co/guide/en/elasticsearch/reference/master/point-in-time-api.html
  */
-#[DSL(module: Module::ELASTICSEARCH, type: Type::EXTRACTOR)]
+#[DocumentationDSL(module: Module::ELASTICSEARCH, type: Type::EXTRACTOR)]
 function from_es(array $config, array $params, ?array $pit_params = null) : ElasticsearchExtractor
 {
     return new ElasticsearchExtractor(

diff --git a/src/adapter/etl-adapter-google-sheet/src/Flow/ETL/Adapter/GoogleSheet/functions.php b/src/adapter/etl-adapter-google-sheet/src/Flow/ETL/Adapter/GoogleSheet/functions.php
@@ -4,7 +4,7 @@
 
 namespace Flow\ETL\Adapter\GoogleSheet;
 
-use Flow\ETL\Attribute\{DSL, Module, Type};
+use Flow\ETL\Attribute\{DocumentationDSL, Module, Type};
 use Flow\ETL\Extractor;
 use Google\Client;
 use Google\Service\Sheets;
@@ -17,7 +17,7 @@
  * @param int $rows_per_page - how many rows per page to fetch from Google Sheets API
  * @param array{dateTimeRenderOption?: string, majorDimension?: string, valueRenderOption?: string} $options
  */
-#[DSL(module: Module::GOOGLE_SHEET, type: Type::EXTRACTOR)]
+#[DocumentationDSL(module: Module::GOOGLE_SHEET, type: Type::EXTRACTOR)]
 function from_google_sheet(
     array|Sheets $auth_config,
     string $spreadsheet_id,
@@ -55,7 +55,7 @@ function from_google_sheet(
  * @param int $rows_per_page - how many rows per page to fetch from Google Sheets API
  * @param array{dateTimeRenderOption?: string, majorDimension?: string, valueRenderOption?: string} $options
  */
-#[DSL(module: Module::GOOGLE_SHEET, type: Type::EXTRACTOR)]
+#[DocumentationDSL(module: Module::GOOGLE_SHEET, type: Type::EXTRACTOR)]
 function from_google_sheet_columns(
     array|Sheets $auth_config,
     string $spreadsheet_id,

diff --git a/src/adapter/etl-adapter-json/src/Flow/ETL/Adapter/JSON/functions.php b/src/adapter/etl-adapter-json/src/Flow/ETL/Adapter/JSON/functions.php
@@ -7,14 +7,14 @@
 use function Flow\ETL\DSL\from_all;
 use Flow\ETL\Adapter\JSON\JSONMachine\JsonExtractor;
 use Flow\ETL\Row\Schema;
-use Flow\ETL\{Attribute\DSL, Attribute\Module, Attribute\Type, Extractor, Loader};
+use Flow\ETL\{Attribute\DocumentationDSL, Attribute\Module, Attribute\Type, Extractor, Loader};
 use Flow\Filesystem\Path;
 
 /**
  * @param array<Path|string>|Path|string $path - string is internally turned into stream
  * @param ?string $pointer - if you want to iterate only results of a subtree, use a pointer, read more at https://github.com/halaxa/json-machine#parsing-a-subtree
  */
-#[DSL(module: Module::JSON, type: Type::EXTRACTOR)]
+#[DocumentationDSL(module: Module::JSON, type: Type::EXTRACTOR)]
 function from_json(
     string|Path|array $path,
     ?string $pointer = null,
@@ -46,7 +46,7 @@ function from_json(
  *
  * @return Loader
  */
-#[DSL(module: Module::JSON, type: Type::LOADER)]
+#[DocumentationDSL(module: Module::JSON, type: Type::LOADER)]
 function to_json(
     string|Path $path,
     int $flags = JSON_THROW_ON_ERROR,

diff --git a/src/adapter/etl-adapter-meilisearch/src/Flow/ETL/Adapter/Meilisearch/functions.php b/src/adapter/etl-adapter-meilisearch/src/Flow/ETL/Adapter/Meilisearch/functions.php
@@ -5,14 +5,14 @@
 namespace Flow\ETL\Adapter\Meilisearch;
 
 use Flow\ETL\Adapter\Meilisearch\MeilisearchPHP\{MeilisearchExtractor, MeilisearchLoader};
-use Flow\ETL\Attribute\{DSL, Module, Type};
+use Flow\ETL\Attribute\{DocumentationDSL, Module, Type};
 use Flow\ETL\Loader;
 use Psr\Http\Client\ClientInterface;
 
 /**
  * @param array{url: string, apiKey: string, httpClient: ?ClientInterface} $config
  */
-#[DSL(module: Module::MEILI_SEARCH, type: Type::LOADER)]
+#[DocumentationDSL(module: Module::MEILI_SEARCH, type: Type::LOADER)]
 function to_meilisearch_bulk_index(
     array $config,
     string $index,
@@ -23,7 +23,7 @@ function to_meilisearch_bulk_index(
 /**
  * @param array{url: string, apiKey: string, httpClient: ?ClientInterface} $config
  */
-#[DSL(module: Module::MEILI_SEARCH, type: Type::LOADER)]
+#[DocumentationDSL(module: Module::MEILI_SEARCH, type: Type::LOADER)]
 function to_meilisearch_bulk_update(
     array $config,
     string $index,
@@ -34,7 +34,7 @@ function to_meilisearch_bulk_update(
 /**
  * Transforms Meilisearch results into clear Flow Rows.
  */
-#[DSL(module: Module::MEILI_SEARCH, type: Type::HELPER)]
+#[DocumentationDSL(module: Module::MEILI_SEARCH, type: Type::HELPER)]
 function meilisearch_hits_to_rows() : MeilisearchPHP\HitsIntoRowsTransformer
 {
     return new MeilisearchPHP\HitsIntoRowsTransformer();
@@ -44,7 +44,7 @@ function meilisearch_hits_to_rows() : MeilisearchPHP\HitsIntoRowsTransformer
  * @param array{url: string, apiKey: string} $config
  * @param array{q: string, limit: ?int, offset: ?int, attributesToRetrieve: ?array<string>, sort: ?array<string>} $params
  */
-#[DSL(module: Module::MEILI_SEARCH, type: Type::EXTRACTOR)]
+#[DocumentationDSL(module: Module::MEILI_SEARCH, type: Type::EXTRACTOR)]
 function from_meilisearch(array $config, array $params, string $index) : MeilisearchExtractor
 {
     return new MeilisearchExtractor($config, $params, $index);