Skip to content

Commit

Permalink
Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@AntonyThorpe
AntonyThorpe committed Jun 7, 2024
1 parent 2b76933 commit f5bd4cd
Show file tree
Hide file tree
Showing 12 changed files with 83 additions and 141 deletions.
6 changes: 2 additions & 4 deletions src/ArrayBulkLoaderSource.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,6 @@
*/
class ArrayBulkLoaderSource extends BulkLoaderSource
{

public function __construct(protected array $data)
{
}
Expand All @@ -20,14 +19,13 @@ public function getIterator(): ArrayIterator
return new ArrayIterator($this->data);
}

public function setData(array $data): static
public function setData(array $data): self
{
$this->data = $data;

return $this;
}

public function getData()
public function getData(): array
{
return $this->data;
}
Expand Down
122 changes: 38 additions & 84 deletions src/BulkLoader.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,39 +39,34 @@ class BulkLoader extends \SilverStripe\Dev\BulkLoader

/**
* Specify a colsure to be run on every imported record.
* @var function
* @var callable
*/
public $recordCallback;

/**
* Bulk loading source
* @var BulkLoaderSource
*/
protected $source;
protected BulkLoaderSource $source;

/**
* Add new records while importing
* @var bool
*/
protected $addNewRecords = true;
protected bool $addNewRecords = true;

/**
* The default behaviour for linking relations
* @var bool
*/
protected $relationLinkDefault = true;
protected bool $relationLinkDefault = true;

/**
* The default behaviour creating relations
* @var bool
*/
protected $relationCreateDefault = true;
protected bool $relationCreateDefault = true;

/**
* Determines whether pages should be published during loading
* @var bool
*/
protected $publishPages = true;
protected bool $publishPages = true;

/**
* Cache the result of getMappableColumns
Expand All @@ -82,49 +77,42 @@ class BulkLoader extends \SilverStripe\Dev\BulkLoader
/**
* Set the BulkLoaderSource for this BulkLoader.
*/
public function setSource(BulkLoaderSource $source)
public function setSource(BulkLoaderSource $source) :static
{
$this->source = $source;
return $this;
}

/**
* Get the BulkLoaderSource for this BulkLoader
* @return BulkLoaderSource $source
*/
public function getSource()
public function getSource(): BulkLoaderSource
{
return $this->source;
}

/**
* Set the default behaviour for linking existing relation objects.
* @param bool $default
* @return \AntonyThorpe\Consumer\BulkLoader
*/
public function setRelationLinkDefault($default)
public function setRelationLinkDefault(bool $default): self
{
$this->relationLinkDefault = $default;
return $this;
}

/**
* Set the default behaviour for creating new relation objects.
* @param bool $default
* @return \AntonyThorpe\Consumer\BulkLoader
*/
public function setRelationCreateDefault($default)
public function setRelationCreateDefault(bool $default): self
{
$this->relationCreateDefault = $default;
return $this;
}

/**
* Set pages to published upon upload
* @param bool $default
* @return \AntonyThorpe\Consumer\BulkLoader
*/
public function setPublishPages($dopubilsh)
public function setPublishPages(bool $dopubilsh): self
{
$this->publishPages = $dopubilsh;
return $this;
Expand All @@ -140,9 +128,8 @@ public function deleteExistingRecords(): void

/**
* Get the DataList of objects this loader applies to.
* @return DataList
*/
public function getDataList()
public function getDataList(): DataList
{
$class = $this->objectClass;
return $class::get();
Expand All @@ -153,15 +140,13 @@ public function getDataList()
* Useful to analyze the input and give the users a chance to influence
* it through a UI.
* @param string $filepath Absolute path to the file we're importing
* @return array See {@link self::processAll()}
* See {@link self::processAll()}
*/
public function preview($filepath)
public function preview($filepath): array
{
return null;
return [];
}



/**
* Start loading of data
* @param string $filepath
Expand All @@ -179,11 +164,10 @@ public function load($filepath = null, $preview = false)

/**
* Import all records from the source
* @param string $filepath
* @param string $filepath
* @param bool $preview
* @return BulkLoaderResult
*/
protected function processAll($filepath, $preview = false)
protected function processAll($filepath, $preview = false): BulkLoaderResult
{
if (!$this->source) {
user_error(
Expand All @@ -200,15 +184,13 @@ protected function processAll($filepath, $preview = false)
return $results;
}


/**
* Process a single record from source
* @param object $record
* @param array $record An map of the data, keyed by the header field defined in {@link self::$columnMap}
* @param array $columnMap
* @param bool $preview
* @param BulkLoaderResult $results
* @param string $preview set to true to prevent writing to the dataobject
* @return BulkLoaderResult
* @param bool $preview set to true to prevent writing to the dataobject
* @return BulkLoaderResult|null
*/
protected function processRecord($record, $columnMap, &$results, $preview = false)
{
Expand Down Expand Up @@ -316,9 +298,8 @@ protected function processRecord($record, $columnMap, &$results, $preview = fals

/**
* Convert the record's keys to the appropriate columnMap keys
* @return array record
*/
protected function columnMapRecord($record)
protected function columnMapRecord(array $record): array
{
$adjustedmap = $this->columnMap;
$newrecord = [];
Expand All @@ -335,10 +316,8 @@ protected function columnMapRecord($record)

/**
* Check if the given mapped record has the required data.
* @param array $mappedrecord
* @return bool
*/
protected function hasRequiredData($mappedrecord)
protected function hasRequiredData(array $mappedrecord): bool
{
if (!is_array($mappedrecord) || $mappedrecord === [] || !array_filter($mappedrecord)) {
return false;
Expand All @@ -358,10 +337,8 @@ protected function hasRequiredData($mappedrecord)

/**
* Perform field transformation or setting of data on placeholder.
* @param DataObject $placeholder
* @param string $field
*/
protected function transformField($placeholder, $field, mixed $value)
protected function transformField(DataObject $placeholder, string $field, mixed $value): void
{
$callback = isset($this->transforms[$field]['callback']) &&
is_callable($this->transforms[$field]['callback']) ?
Expand Down Expand Up @@ -451,27 +428,23 @@ protected function transformField($placeholder, $field, mixed $value)

/**
* Detect if a given record field is a relation field.
* @param string $field
* @return bool
*/
protected function isRelation($field)
protected function isRelation(string $field): bool
{
//get relation name from dot notation
if (str_contains($field, '.')) {
[$field, $columnName] = explode('.', $field);
}
$has_ones = singleton($this->objectClass)->hasOne();
$has_ones = DataObject::singleton($this->objectClass)->hasOne();
//check if relation is present in has ones
return isset($has_ones[$field]);
}

/**
* Given a record field name, find out if this is a relation name
* and return the name
* @param string
* @return string
*/
protected function getRelationName($recordField)
protected function getRelationName(string $recordField): string
{
$relationName = null;
if (isset($this->relationCallbacks[$recordField])) {
Expand All @@ -487,10 +460,8 @@ protected function getRelationName($recordField)
/**
* Find an existing objects based on one or more uniqueness columns
* specified via {@link self::$duplicateChecks}
* @param array $record data
* @return mixed
*/
public function findExistingObject(array $record)
public function findExistingObject(array $record): mixed
{
// checking for existing records (only if not already found)
foreach ($this->duplicateChecks as $fieldName => $duplicateCheck) {
Expand Down Expand Up @@ -536,9 +507,8 @@ public function findExistingObject(array $record)

/**
* Get the field-label mapping of fields that data can be mapped into.
* @return array
*/
public function getMappableColumns()
public function getMappableColumns(): array
{
if ($this->mappableFields !== []) {
return $this->mappableFields;
Expand All @@ -556,14 +526,12 @@ public function getMappableColumns()

/**
* Generate a field-label list of fields that data can be mapped into.
* @param bool $includerelations
* @return array
*/
public function scaffoldMappableFields($includerelations = true)
public function scaffoldMappableFields(bool $includerelations = true): array
{
$map = $this->getMappableFieldsForClass($this->objectClass);
//set up 'dot notation' (Relation.Field) style mappings
if ($includerelations && ($has_ones = singleton($this->objectClass)->hasOne())) {
if ($includerelations && ($has_ones = DataObject::singleton($this->objectClass)->hasOne())) {
foreach ($has_ones as $relationship => $type) {
$fields = $this->getMappableFieldsForClass($type);
foreach ($fields as $field => $title) {
Expand All @@ -578,12 +546,10 @@ public function scaffoldMappableFields($includerelations = true)

/**
* Get the fields and labels for a given class
* @param string $class
* @return array fields
*/
protected function getMappableFieldsForClass($class)
protected function getMappableFieldsForClass(string $class): array
{
$singleton = singleton($class);
$singleton = DataObject::singleton($class);
$fields = (array)$singleton->fieldLabels(false);
foreach (array_keys($fields) as $field) {
if (!$singleton->hasField($field)) {
Expand All @@ -595,10 +561,8 @@ protected function getMappableFieldsForClass($class)

/**
* Format mapping field laabel
* @param string $relationship
* @param string $title
*/
protected function formatMappingFieldLabel($relationship, $title)
protected function formatMappingFieldLabel(string $relationship, string $title): string
{
return sprintf("%s: %s", $relationship, $title);
}
Expand Down Expand Up @@ -632,12 +596,8 @@ public function preprocessChecks(): void

/**
* Update the dataobject with data from the external API
*
* @param array $apidata An array of arrays
* @param bool $preview Set to true to not write
* @return BulkLoaderResult
*/
public function updateRecords(array $apidata, $preview = false)
public function updateRecords(array $apidata, bool $preview = false): BulkLoaderResult
{
$this->setSource(new ArrayBulkLoaderSource($apidata));
$this->addNewRecords = false;
Expand All @@ -647,11 +607,8 @@ public function updateRecords(array $apidata, $preview = false)

/**
* Update/create many dataobjects with data from the external api
*
* @param bool $preview Set to true to not write
* @return BulkLoaderResult
*/
public function upsertManyRecords(array $apidata, $preview = false)
public function upsertManyRecords(array $apidata, bool $preview = false): BulkLoaderResult
{
$this->setSource(new ArrayBulkLoaderSource($apidata));
$this->preprocessChecks();
Expand All @@ -660,11 +617,8 @@ public function upsertManyRecords(array $apidata, $preview = false)

/**
* Delete dataobjects that match to the API data
*
* @param bool $preview Set to true to not write
* @return BulkLoaderResult
*/
public function deleteManyRecords(array $apidata, $preview = false)
public function deleteManyRecords(array $apidata, bool $preview = false): BulkLoaderResult
{
$this->setSource(new ArrayBulkLoaderSource($apidata));
$this->preprocessChecks();
Expand Down Expand Up @@ -709,10 +663,10 @@ public function deleteManyRecords(array $apidata, $preview = false)
* @param array $apidata An array of arrays
* @param string $key The key that matches the column within the Object Class
* @param string $property_name The property name of the class that matches to the key from the API data
* @param bool $preview Set to true to not save
* @param bool $preview Set to true to skip saving
* @return BulkLoaderResult
*/
public function clearAbsentRecords(array $apidata, $key, $property_name, $preview = false)
public function clearAbsentRecords(array $apidata, string $key, string $property_name, bool $preview = false)
{
$results = BulkLoaderResult::create();
$modelClass = $this->objectClass;
Expand Down
Loading

0 comments on commit f5bd4cd

Please sign in to comment.