Adding conditionable method to converter

Author: nyamsprod

CHANGELOG.md

@@ -14,6 +14,9 @@ All Notable changes to `Csv` will be documented in this file
 - `RdbmsResult` class to allow converting RDBMS result into `ResultSet`
 - `TabularData` interface
 - `XMLConverter::supportsHeader`
+- `XMLConverter::when`
+- `HTMLConverter::when`
+- `JsonConverter::when`
 
 ### Deprecated
 
@@ -22,6 +25,10 @@ All Notable changes to `Csv` will be documented in this file
 - `ResultSet::createFromRecords` use `ResultSet::createFromTabularData`
 - `ResultSet::__construct` use `ResultSet::createFromTabularData`
 - `XMLConverter::convert` use `XMLConverter::import` instead
+- `XMLConverter::create` use `XMLConverter::__construct` instead
+- `HTMLConverter::create` use `HTMLConverter::__construct` instead
+- `Statement::create` use `Statement::__construct` instead
+- `FragmentFinder::create` use `FragmentFinder::__construct` instead
 
 ### Fixed
 

README.md

@@ -11,7 +11,7 @@ by utilizing PHP native features whenever possible.
 
 ## Highlights
 
-- Easy to use API
+- Straightforward API
 - Read from and Write to CSV documents in a memory efficient and scalable way
 - Flexible and powerful query features and array to object mapping.
 - Transform CSV documents into popular format (`JSON`, `XML` or `HTML`)

docs/9.0/converter/html.md

@@ -54,13 +54,51 @@ This method sets the optional attribute name for the field name on the HTML `td`
 public HTMLConverter::formatter(?callable $formatter): self
 ```
 
-This method allow to apply a callback prior to converting your collection individual item.
+This method allows to apply a callback prior to converting your collection individual item.
 This callback allows you to specify how each item will be converted. The formatter should
 return an associative array suitable for conversion.
 
 <p class="message-notice">The <code>Formatter</code> callback does not affect the footer
 and/or header conversion.</p>
 
+### HTMLConverter::when
+
+<p class="message-info">New feature introduced in version <code>9.22.0</code></p>
+
+This method allows to conditionally create your converter depending on the success or
+failure of a condition.
+
+```php
+use League\Csv\HTMLConverter;
+
+$converter = (new HTMLConverter());
+if ($condition) {
+    $converter = $converter->td('data-field');
+} else {
+    $converter = $converter->td('');
+}
+```
+
+becomes
+
+```php
+$converter = (new HTMLConverter())
+    ->when(
+        $condition,
+        fn (HTMLConverter $c) => $c->td('data-field'),
+        fn (HTMLConverter $c) => $c->td(''),
+    );
+)
+```
+
+The `else` expression is not required but if present in **MUST BE** a callable which only
+accepts the `HTMLConverter` instance and returns `null` or a `HTMLConverter` instance.
+
+The only requirements are:
+
+- that the condition is a `boolean` or a callable that returns a `boolean`.
+- the callback returns a `HTMLConverter` instance or null.
+
 ## Conversion
 
 <p class="message-info">Since version <code>9.3.0</code> this method accepts optional header and footer records to display them in the exported HTML table.</p>
@@ -85,7 +123,7 @@ $sth = $dbh->prepare("SELECT firstname, lastname, email FROM users LIMIT 2");
 $sth->setFetchMode(PDO::FETCH_ASSOC);
 $sth->execute();
 
-$converter = (new HTMLConverter())
+$converter = new HTMLConverter()
     ->table('table-csv-data', 'users')
     ->tr('data-record-offset')
     ->td('title')

docs/9.0/converter/index.md

@@ -9,7 +9,6 @@ title: Records conversion in popular formats
 
 The package provides classes which convert any collection of CSV records into:
 
-- another collection encoded using the [CharsetConverter](/9.0/converter/charset/) class;
 - a `DOMDocument` object using the [XMLConverter](/9.0/converter/xml/) class;
 - an HTML table using the [HTMLConverter](/9.0/converter/html/) class;
 - an JSON document using the [JsonConverter](/9.0/converter/json/) class;

docs/9.0/converter/json.md

@@ -143,6 +143,43 @@ be lower than one otherwise a exception will be thrown.
 $converter = JsonConverter::create()->chunkSize(1_000);
 $converter->chunkSize; //returns the value used
 ```
+### JsonConverter::when
+
+<p class="message-info">New feature introduced in version <code>9.22.0</code></p>
+
+This method allows to conditionally create your converter depending on the success or
+failure of a condition.
+
+```php
+use League\Csv\JsonConverter;
+
+$converter = JsonConverter::create();
+if ($condition) {
+    $converter = $converter->chunkSize(1_000);
+} else {
+    $converter = $converter->chunkSize(200);
+}
+```
+
+becomes
+
+```php
+$stmt = JsonConverter::create()
+    ->when(
+        $condition,
+        fn (JsonConverter $c) => $c->chunkSize(1_000),
+        fn (JsonConverter $c) => $c->chunkSize(200),
+    );
+)
+```
+
+The `else` expression is not required but if present in **MUST BE** a callable which only
+accepts the `JsonConverter` instance and returns `null` or a `JsonConverter` instance.
+
+The only requirements are:
+
+- that the condition is a `boolean` or a callable that returns a `boolean`.
+- the callback returns a `JsonConverter` instance or null.
 
 ## Conversion
 

docs/9.0/converter/xml.md

@@ -100,15 +100,15 @@ $csv = Reader::createFromPath('/path/to/prenoms.csv', 'r');
 $csv->setDelimiter(';');
 $csv->setHeaderOffset(0);
 
-$stmt = (new Statement())
+$stmt = new Statement()
     ->where(function (array $record) {
         return 'Anaïs' === $record['prenoms'];
     })
     ->offset(0)
     ->limit(2)
 ;
 
-$converter = (new XMLConverter())
+$converter = new XMLConverter()
     ->rootElement('csv')
     ->recordElement('record', 'offset')
     ->fieldElement('field', 'name')
@@ -148,6 +148,44 @@ echo htmlentities($dom->saveXML());
 // </root>
 ```
 
+### XMLConverter::when
+
+<p class="message-info">New feature introduced in version <code>9.22.0</code></p>
+
+This method allows to conditionally create your converter depending on the success or
+failure of a condition.
+
+```php
+use League\Csv\XMLConverter;
+
+$converter = (new XMLConverter());
+if ($condition) {
+    $converter = $converter->fieldElement(null);
+} else {
+    $converter = $converter->fieldElement('cell');
+}
+```
+
+becomes
+
+```php
+$stmt = (new XMLConverter())
+    ->when(
+        $condition,
+        fn (XMLConverter $c) => $c->fieldElement(null),
+        fn (XMLConverter $c) => $c->fieldElement('cell'),
+    );
+)
+```
+
+The `else` expression is not required but if present in **MUST BE** a callable which only
+accepts the `XMLConverter` instance and returns `null` or a `XMLConverter` instance.
+
+The only requirements are:
+
+- that the condition is a `boolean` or a callable that returns a `boolean`.
+- the callback returns a `XMLConverter` instance or null.
+
 ## Conversion
 
 <p class="message-notice">The method is deprecated in version <code>9.22.0</code> use <code>XMLConverter::import</code> instead</p>
@@ -167,15 +205,15 @@ $csv = Reader::createFromPath('/path/to/prenoms.csv', 'r');
 $csv->setDelimiter(';');
 $csv->setHeaderOffset(0);
 
-$stmt = (new Statement())
+$stmt = new Statement()
     ->where(function (array $record) {
         return 'Anaïs' === $record['prenoms'];
     })
     ->offset(0)
     ->limit(2)
 ;
 
-$converter = (new XMLConverter())
+$converter = new XMLConverter()
     ->rootElement('csv')
     ->recordElement('record', 'offset')
     ->fieldElement('field', 'name')
@@ -233,7 +271,7 @@ header('Content-Type: text/xml; charset=UTF-8');
 header('Content-Description: File Transfer');
 header('Content-Disposition: attachment; filename="name-for-your-file.xml"');
 
-XMLConverter::create()->download($reader);
+new XMLConverter()->download($reader);
 die;
 ```
 
@@ -256,7 +294,7 @@ header('Cache-Control: no-cache, no-store, must-revalidate');
 header('Pragma: no-cache');
 header('Expires: 0');
  //the filename will be the name of the downloaded xml as shown by your HTTP client!
-XMLConverter::create()->download($reader, 'name-for-your-file.xml');
+new XMLConverter()->download($reader, 'name-for-your-file.xml');
 die;
 ```
 
@@ -275,7 +313,7 @@ $reader->setHeaderOffset(0);
 header('Cache-Control: no-cache, no-store, must-revalidate');
 header('Pragma: no-cache');
 header('Expires: 0');
-XMLConverter::create()->download(
+new XMLConverter()->download(
     records: $reader,
     filename: 'generated_file.xml',
     encoding: 'iso-8859-1',

docs/9.0/extensions/doctrine.md

@@ -28,7 +28,7 @@ $csv = Reader::createFromPath('/path/to/my/file.csv');
 $csv->setHeaderOffset(0);
 $csv->setDelimiter(';');
 
-$criteria = Statement::create()
+$criteria = (new Statement())
     ->andWhere('prenom', '=', 'Adam')
     ->orderByAsc('annee')
     ->orderByDesc('foo')
@@ -114,7 +114,7 @@ $csv = Reader::createFromPath('/path/to/my/file.csv');
 $csv->setHeaderOffset(0);
 $csv->setDelimiter(';');
 
-$stmt = Statement::create()
+$stmt = (new Statement())
     ->where(fn (array $row): bool => isset($row['email']) && str_ends_with($row['email'], '@github.com'));
 
 $collection = new RecordCollection($stmt->process($csv));

docs/9.0/index.md

@@ -28,7 +28,7 @@ $csv->setHeaderOffset(0); //set the CSV header offset
 $csv->setEscape(''); //required in PHP8.4+ to avoid deprecation notices
 
 //get 25 records starting from the 11th row
-$stmt = Statement::create()
+$stmt = new Statement()
     ->offset(10)
     ->limit(25)
 ;
@@ -140,7 +140,7 @@ $csv->setDelimiter(';');
 $csv->setHeaderOffset(0);
 $csv->setEscape(''); //required in PHP8.4+ to avoid deprecation notices
 
-$converter = (new XMLConverter())
+$converter = new XMLConverter()
     ->rootElement('csv')
     ->recordElement('record', 'offset')
     ->fieldElement('field', 'name')

docs/9.0/reader/resultset.md

@@ -82,7 +82,7 @@ foreach ($records as $record) {
 }
 
 $reader = Reader::createFromFileObject($tmp)->setHeaderOffset(0);
-$stmt = Statement::create()->offset(1)->limit(1);
+$stmt = (new Statement())->offset(1)->limit(1);
 $result = $stmt->process($reader);
 
 echo '<pre>', PHP_EOL;