Creating a new statement type

Here's the documentation for supporting a new type of statement:

1. Create the new Upload class.

There is an abstract Upload class in the class/Upload directory that contains the common functionality across all Upload types. Create a new class in this directory named accordingly.

<?php
namespace SHIFT\TrackShift\Upload;

class ExampleUpload extends Upload {
}

2. Assign known columns

Assign the KNOWN_COLUMNS constant to an array containing the strings of known column names for the given type. This doesn't matter whether it's a CSV, TSV, Excel, or whatever - all file types will have "columns" of some sort.

However many columns you KNOW much exist in this type should be listed, to avoid ambiguity with other upload types.

class ExampleUpload extends Upload {
	const KNOWN_COLUMNS = ["Song Code", "Earning ID", "Another known column"];
}

3. Implement extraction functions

Each upload type will have a different way to extract the artist name, product title, earning, and date. This is usually just done by matching a specific column in a row of data, but sometimes is more complex.

public function extractEarning(array $row):string {
	return $row["Gross Amount"] - $row["Sales Fee"];
}

4. Handle statements that require preloading

Some statements don't actually store information on "products". Instead they store information on tracks/tunes within products. This means that before the statement can be processed, the individual products need to be extracted, via preloading.

To preload your statement, mark the class constant REQUIRES_PRELOADING to true and implement the loadUsageForInternalLookup(array $row):void function. This function can do anything you want it to, and will be supplied with every row in the statement individually. Do whatever you need with it in this function.

5. Optionally hard-code the currency

Usually the currency can be inferred from the contents of the rows, but if a statement is always in a certain currency, create a class constant of CURRENCY_OVERRIDE and set it to the three-letter currency code.

6. Match the upload class with the file extension function

In UploadReposity.php::detectUploadType match the class name to the appropriate function for each filetype.

e.g. for AWAL.csv go to detectUploadTypeFromCsv and perform the correct match (likely column headers)

7. Make nice name for Uploads table

Go to Upload::__construct and add class matched with friendly name.

---