Changes proposed in this Pull Request:

This pull request builds an engine for generating printable order receipts based on the transient files engine: the generated receipts will be transient files with a public unauthenticated URL. The design of the receipts mimicks the one for the receipts shown by the WooCommerce mobile applications.

More specifically, this pull request adds:

• A ReceiptRenderingEngine class with two methods: generate_receipt and get_existing_receipt. These are wrappers around TransientFilesEngine.
• A ReceiptRenderingRestController class that provides two REST API endpoints, one GET and one POST, both having the URL /orders/<order id>/receipt. The difference is that the POST endpoint will create a new receipt if one doesn't exist already, while the GET endpoint won't. (A receipt exists if it has been created via either direct call to ReceiptRenderingEngine::generate_receipt or the POST endpoint, and has not expired yet)

In order to match existing receipts with orders, a new order meta key is introduced, _receipt_file_name, whose value is the name of the last receipt (transient) file created for the order. Note that the file pointed by this meta value might not exist anymore (the transient files cleanup procedure for expired files doesn't delete associated order meta keys), the engine takes this in account when searching existing receipts.

The POST endpoint accepts three optional query string arguments:

• expiration_date: Formatted as yyyy-mm-dd.
• expiration_days: A number, 0 is today, 1 is tomorrow, etc.
• force_new: Defaults to false, if true, creates a new receipt even if one already exists for the order.

If neither expiration_date nor expiration_days are supplied, the default is expiration_days = 1 (so the receipt expires the following day). Remember that the expiration time for transient files is 23:59:59 of the expiration date.

This pull request also introduces a a bit of additional infrastructure for the REST API in general:

• A modification in Server.php to allow creating REST API controller classes in the src directory (the dependency injection engine is used to locate them).
• A RestApiControllerBase class (in src/Internal) that should be used as the base class for new REST API controller classes. The ReceiptRenderingRestController class inherits from it.

This extra infrastructure is added to support our policy of not adding any new code in includes whenever possible.

Additionally, this pull request introduces an addition to the original transient files engine: an .htaccess file with content deny for all and and empty index.html file will be created in the default directory for transient files (in a migration if the directory already exists, at the moment it's created if not) in order to prevent listing the directory contents.

How to test the changes in this Pull Request:

To test the engine in full, an order that has the following is required:

• At least one simple and one variable product.
• At least two discount coupons applied.
• Fees.
• Shipping costs.
• Taxes.
• Customer order notes.

Additionally, the order should be paid using a credit card with WooCommerce Payments.

Since testing with WooCommerce Payments isn't trivial (it's not possible in a local environment), a mechanism is added to ease testing. If the WCPAY_DEV_MODE constant exists with a value of true and the order has a meta entry with the key _wcpay_payment_details, the value of this meta entry (after being JSON decoded) will be used as if it was the "payment_details" key in the data returned by the Stripe "get intent" API endpoint (containing at least the "card_present" key), which is what the engine normally does in order to retrieve the payment information for the order (taking the intent id from the _intent_id order meta item).

Thus, if you have successfully created an order in a non-local site and have paid it with WooCommerce Payments, you can get the intent information from the order as follows:

wp eval 'echo json_encode(WC_Payments::get_payments_api_client()->get_intent(wc_get_order(<order_id>)->get_meta("_intent_id")));'

...and then save the value in an _intent_data meta entry for an existing order locally (remember to define WCPAY_DEV_MODE too if you don't have WooCommerce Payments installed locally, or you don't have it in dev mode).

Alternatively, you can create a meta entry with artificial intent data from a wp shell as follows (the intent data is simplified to contain only the information required for the receipt):

$o=wc_get_order(<order id>);
$o->update_meta_data('_wcpay_payment_details', '{"card_present":{"brand":"visa","last4":"1234","receipt":{"account_type":"credit","application_preferred_name":"Stripe Credit","dedicated_file_name":"A000000003101001"}}}');
$o->save_meta_data();

Once the order is in place, you can test the code API as follows:

wp eval 'echo wc_get_container()->get(Automattic\WooCommerce\Internal\ReceiptRendering\ReceiptRenderingEngine::class)->generate_receipt(<order id>, null, true);'

You will get a file name, which you can translate to a full path with:

wp eval 'echo wc_get_container()->get(Automattic\WooCommerce\Internal\TransientFiles\TransientFilesEngin e::class)->get_transient_file_path("<file name>");'

Verify that the file actually exists with ls <full file path>; or directly see the file contents with cat <full file path>, or by opening it in a text editor.

You can also get the public URL of the file with:

wp eval 'echo wc_get_container()->get(Automattic\WooCommerce\Internal\TransientFiles\TransientFilesEngin e::class)->get_public_url("<file name>");'

Then open the URL in a browser to see the receipt.

The null passed to generate_receipt means "default expiration" (so the following day), try passing a date in yyyy-mm-dd format instead. The true passed after that means "force the generation of a new receipt", try to pass it as false and you'll geat the same file name with every call after the first one.

Now, as for the REST API endpoints, you can use PostMan or curl (assuming you have a basic authentication plugin in place):

curl -X POST -u <user>:<password> http://localhost:8034/wp-json/wc/v3/orders/<order id>/receipt?force_new=true

You should be able to paste the value of receipt_url from the received JSON in the address bar of your browser, and then you'll see the receipt.

As with the case of the code API, you can try setting force_new to false, or adding expiration_date or expiration_days to the query string.

Also, try with the GET endpoint and verify that you get a 404 error if no receipt exist for the order. Remember that "receipt exists for an order" means that a _receipt_file_name meta entry exists for the order and the transient file pointed by the entry exists.

Changelog entry

• Automatically create a changelog entry from the details below.