Beautiful Open-Source Form Builder
Improve Stripe tax exports and add chunked datasets
Julien Nahuma9ca8d99c10a
diff --git a/api/.gitignore b/api/.gitignoreindex f2c4f78fc..4c6b046b1 100644--- a/api/.gitignore+++ b/api/.gitignore@@ -30,3 +30,5 @@ public/.DS_Store_ide_helper.phpdocker-compose.override.yml/.make.*+/storage/app/stripe-export-datasets/*+!/storage/app/stripe-export-datasets/.gitignorediff --git a/api/app/Console/Commands/Tax/BuildStripeExportDataset.php b/api/app/Console/Commands/Tax/BuildStripeExportDataset.phpnew file mode 100644index 000000000..9f5e508ce--- /dev/null+++ b/api/app/Console/Commands/Tax/BuildStripeExportDataset.php@@ -0,0 +1,146 @@+<?php++namespace App\Console\Commands\Tax;++use App\Services\Tax\StripeExportDatasetStore;+use Carbon\Carbon;+use Carbon\CarbonPeriod;+use Illuminate\Console\Command;+use Symfony\Component\Process\Process;++class BuildStripeExportDataset extends Command+{+ protected $signature = 'stripe:build-export-dataset+ {--dataset= : Dataset id}+ {--start-date= : Start date (YYYY-MM-DD)}+ {--end-date= : End date (YYYY-MM-DD)}+ {--full-month : Use the full month of the start date}+ {--chunk=week : Chunk by week or month}+ {--concurrency=4 : Max concurrent chunk collectors}';++ protected $description = 'Build a reusable Stripe export dataset in chunked parallel batches';++ public function handle(StripeExportDatasetStore $store): int+ {+ [$startDate, $endDate] = $this->resolveDateRange();+ if (!$startDate || !$endDate) {+ return Command::FAILURE;+ }++ $chunkBy = (string) $this->option('chunk');+ $concurrency = max(1, (int) $this->option('concurrency'));+ $datasetId = (string) ($this->option('dataset') ?: "{$startDate}_{$endDate}_{$chunkBy}");++ $chunks = $this->buildChunks($startDate, $endDate, $chunkBy);+ $store->initialize($datasetId, [+ 'start_date' => $startDate,+ 'end_date' => $endDate,+ 'chunk_by' => $chunkBy,+ 'concurrency' => $concurrency,+ ]);++ $this->info("Dataset: {$datasetId}");+ $this->info('Chunks: ' . count($chunks));++ $pending = $chunks;+ $running = [];++ while (!empty($pending) || !empty($running)) {+ while (count($running) < $concurrency && !empty($pending)) {+ $chunk = array_shift($pending);+ $process = new Process([+ PHP_BINARY,+ base_path('artisan'),+ 'stripe:collect-export-dataset-chunk',+ '--dataset=' . $datasetId,+ '--start-date=' . $chunk['start_date'],+ '--end-date=' . $chunk['end_date'],+ ], base_path());+ $process->setTimeout(null);+ $process->start();++ $chunk['process'] = $process;+ $running[] = $chunk;+ $this->line("Started chunk {$chunk['start_date']} -> {$chunk['end_date']}");+ }++ foreach ($running as $index => $chunk) {+ /** @var Process $process */+ $process = $chunk['process'];+ if (!$process->isRunning()) {+ if (!$process->isSuccessful()) {+ $this->error("Chunk failed {$chunk['start_date']} -> {$chunk['end_date']}");+ $this->line($process->getErrorOutput() ?: $process->getOutput());+ return Command::FAILURE;+ }++ $this->line("Completed chunk {$chunk['start_date']} -> {$chunk['end_date']}");+ unset($running[$index]);+ }+ }++ usleep(200000);+ }++ $rows = $store->mergeChunks($datasetId);+ $this->info('Dataset ready: ' . $store->datasetRowsPath($datasetId));+ $this->info('Rows: ' . count($rows));++ return Command::SUCCESS;+ }++ private function resolveDateRange(): array+ {+ $startDate = $this->option('start-date');+ $endDate = $this->option('end-date');++ if (!$startDate) {+ $startDate = Carbon::now()->subMonth()->startOfMonth()->format('Y-m-d');+ } elseif (!Carbon::createFromFormat('Y-m-d', $startDate)) {+ $this->error('Invalid start date format. Use YYYY-MM-DD.');+ return [null, null];+ }++ if (!$endDate) {+ $endDate = Carbon::parse($startDate)->endOfMonth()->format('Y-m-d');+ } elseif (!Carbon::createFromFormat('Y-m-d', $endDate)) {+ $this->error('Invalid end date format. Use YYYY-MM-DD.');+ return [null, null];+ }++ return [$startDate, $endDate];+ }++ private function buildChunks(string $startDate, string $endDate, string $chunkBy): array+ {+ $start = Carbon::parse($startDate)->startOfDay();+ $end = Carbon::parse($endDate)->endOfDay();+ $chunks = [];++ if ($chunkBy === 'month') {+ $cursor = $start->copy()->startOfMonth();+ while ($cursor->lte($end)) {+ $chunkStart = $cursor->copy()->max($start);+ $chunkEnd = $cursor->copy()->endOfMonth()->min($end);+ $chunks[] = [+ 'start_date' => $chunkStart->format('Y-m-d'),+ 'end_date' => $chunkEnd->format('Y-m-d'),+ ];+ $cursor->addMonth()->startOfMonth();+ }++ return $chunks;+ }++ foreach (CarbonPeriod::create($start, '7 days', $end) as $periodStart) {+ $chunkStart = $periodStart->copy()->max($start);+ $chunkEnd = $periodStart->copy()->addDays(6)->endOfDay()->min($end);+ $chunks[] = [+ 'start_date' => $chunkStart->format('Y-m-d'),+ 'end_date' => $chunkEnd->format('Y-m-d'),+ ];+ }++ return $chunks;+ }+}diff --git a/api/app/Console/Commands/Tax/CollectStripeExportDatasetChunk.php b/api/app/Console/Commands/Tax/CollectStripeExportDatasetChunk.phpnew file mode 100644index 000000000..5bfa8d6e7--- /dev/null+++ b/api/app/Console/Commands/Tax/CollectStripeExportDatasetChunk.php@@ -0,0 +1,50 @@+<?php++namespace App\Console\Commands\Tax;++use App\Services\Tax\StripeExportDatasetService;+use App\Services\Tax\StripeExportDatasetStore;+use Illuminate\Console\Command;+use Illuminate\Support\Facades\Cache;++class CollectStripeExportDatasetChunk extends Command+{+ protected $signature = 'stripe:collect-export-dataset-chunk+ {--dataset= : Dataset id}+ {--start-date= : Start date (YYYY-MM-DD)}+ {--end-date= : End date (YYYY-MM-DD)}';++ protected $description = 'Collect a single Stripe export dataset chunk';++ public function handle(StripeExportDatasetService $collector, StripeExportDatasetStore $store): int+ {+ $datasetId = (string) $this->option('dataset');+ $startDate = (string) $this->option('start-date');+ $endDate = (string) $this->option('end-date');++ if (!$datasetId || !$startDate || !$endDate) {+ $this->error('dataset, start-date and end-date are required.');+ return Command::FAILURE;+ }++ $chunkKey = "{$startDate}_{$endDate}";+ Cache::put("stripe-export-dataset:{$datasetId}:{$chunkKey}", [+ 'status' => 'running',+ 'started_at' => now()->toIso8601String(),+ ], now()->addDay());++ $payload = $collector->collect($startDate, $endDate);+ $store->writeChunk($datasetId, $chunkKey, $payload['rows'], $payload['stats']);++ Cache::put("stripe-export-dataset:{$datasetId}:{$chunkKey}", [+ 'status' => 'completed',+ 'completed_at' => now()->toIso8601String(),+ 'row_count' => count($payload['rows']),+ 'stats' => $payload['stats'],+ ], now()->addDay());++ $this->info("Collected {$chunkKey}: " . count($payload['rows']) . ' rows');++ return Command::SUCCESS;+ }+}diff --git a/api/app/Console/Commands/Tax/GenerateDesXmlExport.php b/api/app/Console/Commands/Tax/GenerateDesXmlExport.phpindex b56f5f15d..e24239f02 100644--- a/api/app/Console/Commands/Tax/GenerateDesXmlExport.php+++ b/api/app/Console/Commands/Tax/GenerateDesXmlExport.php@@ -2,6 +2,8 @@namespace App\Console\Commands\Tax;+use App\Services\Tax\StripeExportDatasetService;+use App\Services\Tax\StripeExportDatasetStore;use Carbon\Carbon;use Illuminate\Console\Command;use Laravel\Cashier\Cashier;@@ -43,6 +45,7 @@ class GenerateDesXmlExport extends Commandprotected $signature = 'stripe:generate-des-xml{--start-date= : Start date (YYYY-MM-DD)}{--end-date= : End date (YYYY-MM-DD)}+ {--dataset= : Reuse a built dataset id}{--full-month : Use the full month of the start date}{--vat= : French VAT number (must start with FR)}';@@ -56,7 +59,7 @@ class GenerateDesXmlExport extends Commandprivate const DECLARATION_TYPE = 'DES';private const FLUX_TYPE = 'INTRODUCTION';- public function handle()+ public function handle(StripeExportDatasetService $collector, StripeExportDatasetStore $store){// Validate required options$vatNumber = $this->option('vat');@@ -98,8 +101,25 @@ class GenerateDesXmlExport extends Command$this->info('Start date: ' . $startDate);$this->info('End date: ' . $endDate);- // Get invoices- $invoices = $this->getInvoices($startDate, $endDate);+ $datasetId = $this->option('dataset');+ if ($datasetId) {+ $rows = $store->loadRows($datasetId);+ } else {+ $rows = $collector->collect($startDate, $endDate)['rows'];+ }++ $invoices = array_values(array_filter(array_map(function (array $row) {+ if (!($row['des_eligible'] ?? false)) {+ return null;+ }++ return [+ 'country_code' => $row['des_country_code'],+ 'vat_number' => $row['des_vat_number'],+ 'amount_eur' => $row['des_amount_eur'],+ 'created_at' => $row['created_ts'],+ ];+ }, $rows)));// Generate XML$xml = $this->generateXml($invoices);@@ -169,6 +189,11 @@ class GenerateDesXmlExport extends Commandcontinue;}+ $netInvoiceAmount = $this->getNetInvoiceAmount($invoice);+ if (($invoice->total ?? 0) > 0 && $netInvoiceAmount <= 0) {+ continue;+ }+// Only process EU B2B invoices with VAT numberif (!$this->isEligibleForDes($invoice)) {continue;@@ -269,9 +294,11 @@ class GenerateDesXmlExport extends Commandprivate function getInvoiceAmountInEur(Invoice $invoice): ?float{+ $netInvoiceAmount = $this->getNetInvoiceAmount($invoice);+// If the invoice is already in EUR, just convert from centsif ($invoice->currency === 'eur') {- return $invoice->amount_paid / 100;+ return $netInvoiceAmount / 100;}// Try to get the converted amount from the balance transaction@@ -282,7 +309,7 @@ class GenerateDesXmlExport extends Command$netEur = $bt->amount ?? 0;$feeEur = $bt->fee ?? 0;$totalEur = $netEur + $feeEur; // GROSS = NET + fees- return $totalEur / 100;+ return $this->applyInvoiceAdjustmentsToGrossAmount($invoice, $totalEur / 100);}// Fallback: Stripe no longer embeds charge on invoice@@ -302,7 +329,7 @@ class GenerateDesXmlExport extends Command$netEur = $bt->amount ?? 0;$feeEur = $bt->fee ?? 0;$totalEur = $netEur + $feeEur; // GROSS = NET + fees- return $totalEur / 100;+ return $this->applyInvoiceAdjustmentsToGrossAmount($invoice, $totalEur / 100);}} catch (\Exception $e) {// Silently continue if charge retrieval fails@@ -316,7 +343,7 @@ class GenerateDesXmlExport extends Command$netEur = $bt->amount ?? 0;$feeEur = $bt->fee ?? 0;$totalEur = $netEur + $feeEur;- return $totalEur / 100;+ return $this->applyInvoiceAdjustmentsToGrossAmount($invoice, $totalEur / 100);}}}@@ -326,6 +353,44 @@ class GenerateDesXmlExport extends Commandreturn null;}+ private function getInvoiceRefundAmount(Invoice $invoice): int+ {+ $invoiceRefundAmount = (int) ($invoice->amount_refunded ?? 0);+ $chargeRefundAmount = 0;++ if (isset($invoice->charge)) {+ $chargeRefundAmount = (int) ($invoice->charge->amount_refunded ?? 0);++ if ($chargeRefundAmount === 0 && isset($invoice->charge->refunded) && $invoice->charge->refunded) {+ $chargeRefundAmount = (int) ($invoice->total ?? 0);+ }+ }++ return max($invoiceRefundAmount, $chargeRefundAmount);+ }++ private function getInvoiceCreditNotesAmount(Invoice $invoice): int+ {+ return (int) (($invoice->post_payment_credit_notes_amount ?? 0) + ($invoice->pre_payment_credit_notes_amount ?? 0));+ }++ private function getNetInvoiceAmount(Invoice $invoice): int+ {+ return (int) (($invoice->total ?? 0) - $this->getInvoiceRefundAmount($invoice) - $this->getInvoiceCreditNotesAmount($invoice));+ }++ private function applyInvoiceAdjustmentsToGrossAmount(Invoice $invoice, float $grossAmount): float+ {+ $originalAmount = (int) ($invoice->total ?? 0);+ $netAmount = $this->getNetInvoiceAmount($invoice);++ if ($originalAmount === 0 || $grossAmount == 0.0 || $netAmount === $originalAmount) {+ return $grossAmount;+ }++ return $grossAmount * ($netAmount / $originalAmount);+ }+/*** Get exchange rate for a currency to EUR* You might want to use a more sophisticated exchange rate service in productiondiff --git a/api/app/Console/Commands/Tax/GenerateTaxExport.php b/api/app/Console/Commands/Tax/GenerateTaxExport.phpindex 65a767a9c..445dbef51 100644--- a/api/app/Console/Commands/Tax/GenerateTaxExport.php+++ b/api/app/Console/Commands/Tax/GenerateTaxExport.php@@ -3,6 +3,8 @@namespace App\Console\Commands\Tax;use App\Exports\Tax\ArrayExport;+use App\Services\Tax\StripeExportDatasetService;+use App\Services\Tax\StripeExportDatasetStore;use Carbon\Carbon;use Illuminate\Console\Command;use Laravel\Cashier\Cashier;@@ -18,6 +20,7 @@ class GenerateTaxExport extends Commandprotected $signature = 'stripe:generate-stripe-export{--start-date= : Start date (YYYY-MM-DD)}{--end-date= : End date (YYYY-MM-DD)}+ {--dataset= : Reuse a built dataset id}{--full-month : Use the full month of the start date}';/**@@ -62,7 +65,7 @@ class GenerateTaxExport extends Command** @return int*/- public function handle()+ public function handle(StripeExportDatasetService $collector, StripeExportDatasetStore $store){// Start the processing timer$startTime = microtime(true);@@ -94,133 +97,17 @@ class GenerateTaxExport extends Command$this->info('Start date: ' . $startDate);$this->info('End date: ' . $endDate);- $processedInvoices = [];-- // Create a progress bar- $queryOptions = [- 'limit' => 100, // Maximum allowed by Stripe API- 'expand' => [- 'data.customer',- 'data.customer.address',- 'data.customer.tax_ids',- 'data.payment_intent',- 'data.payment_intent.payment_method',- 'data.charge.balance_transaction',- 'data.automatic_tax',- 'data.total_tax_amounts'- ],- 'status' => 'paid',- ];- if ($startDate) {- $queryOptions['created']['gte'] = Carbon::parse($startDate)->startOfDay()->timestamp;- }- if ($endDate) {- $queryOptions['created']['lte'] = Carbon::createFromFormat('Y-m-d', $endDate)->endOfDay()->timestamp;+ $datasetId = $this->option('dataset');+ if ($datasetId) {+ $datasetRows = $store->loadRows($datasetId);+ $stats = $store->readMetadata($datasetId);+ } else {+ $payload = $collector->collect($startDate, $endDate);+ $datasetRows = $payload['rows'];+ $stats = $payload['stats'];}- $this->info('Fetching invoices from Stripe...');- $invoices = Cashier::stripe()->invoices->all($queryOptions);- $totalResults = $invoices->count();- $this->info("Initial batch contains {$totalResults} invoices");-- $bar = $this->output->createProgressBar();- $bar->start();-- // Improved counters for better tracking- $paymentNotSuccessfulCount = 0;- $refundedInvoicesCount = 0;- $missingDataInvoicesCount = 0;- $totalInvoice = 0;- $processedInvoiceCount = 0;- $defaultedToFranceCount = 0;-- // Volume metrics- $grossVolumeUsd = 0;- $netVolumeUsd = 0;- $taxTotalUsd = 0;- $grossVolumeEur = 0;- $netVolumeEur = 0;- $taxTotalEur = 0;-- do {- if (empty($invoices->data)) {- $this->line('No invoices found in this batch.');- break;- }-- foreach ($invoices as $invoice) {- $totalInvoice++;-- // Check for payment status- // Since we query with status='paid', check invoice status first- // payment_intent->status may not always be available/expanded- $invoiceStatus = $invoice->status ?? null;- $paymentIntentStatus = $invoice->payment_intent->status ?? null;-- // Accept if invoice is paid OR payment_intent succeeded- if ($invoiceStatus !== 'paid' && $paymentIntentStatus !== 'succeeded') {- $paymentNotSuccessfulCount++;- continue;- }-- // Check if invoice was refunded- if (isset($invoice->charge) && isset($invoice->charge->refunded) && $invoice->charge->refunded) {- $refundedInvoicesCount++;- continue;- }-- try {- $formattedInvoice = $this->formatInvoice($invoice);-- // Check if we defaulted to France- if ($formattedInvoice['cust_country'] === 'FR' && $formattedInvoice['_defaulted_to_fr'] === true) {- $defaultedToFranceCount++;- }-- // Remove the internal tracking field- unset($formattedInvoice['_defaulted_to_fr']);-- $processedInvoices[] = $formattedInvoice;- $processedInvoiceCount++;-- // Track volume metrics- $grossVolumeUsd += $formattedInvoice['total_usd'];- $netVolumeUsd += $formattedInvoice['total_after_tax_usd'];- $taxTotalUsd += $formattedInvoice['tax_total_usd'];- $grossVolumeEur += $formattedInvoice['total_eur'];- $netVolumeEur += $formattedInvoice['total_after_tax_eur'];- $taxTotalEur += $formattedInvoice['tax_total_eur'];- } catch (\Exception $e) {- $this->warn("Error processing invoice {$invoice->id}: {$e->getMessage()}");- $missingDataInvoicesCount++;- continue;- }-- // Advance the progress bar- $bar->advance();- }-- // Safe pagination- try {- $lastInvoice = end($invoices->data);- if ($lastInvoice) {- $queryOptions['starting_after'] = $lastInvoice->id;- } else {- break;- }-- // No need for sleep - Stripe API can handle the request rate- $invoices = Cashier::stripe()->invoices->all($queryOptions);- $batchSize = count($invoices->data);- $totalResults += $batchSize;- } catch (\Exception $e) {- $this->error("Error fetching next batch of invoices: {$e->getMessage()}");- break;- }- } while ($invoices->has_more);-- $bar->finish();- $this->line('');+ $processedInvoices = array_map(fn (array $row) => $collector->toTaxExportRow($row), $datasetRows);$aggregatedReport = $this->aggregateReport($processedInvoices);@@ -236,15 +123,22 @@ class GenerateTaxExport extends Command// Display the results with improved statistics$this->info('Processing completed in ' . $executionTime . ' seconds');- $this->info('Total invoices found: ' . $totalInvoice);- $this->info('Processed invoices: ' . $processedInvoiceCount);+ $this->info('Total invoices found: ' . ($stats['total_invoice'] ?? count($datasetRows)));+ $this->info('Processed invoices: ' . ($stats['processed_invoice_count'] ?? count($processedInvoices)));$this->info('Excluded invoices:');- $this->info(' - Payment not successful: ' . $paymentNotSuccessfulCount);- $this->info(' - Refunded: ' . $refundedInvoicesCount);- $this->info(' - Missing required data: ' . $missingDataInvoicesCount);- $this->info(' - Defaulted to France: ' . $defaultedToFranceCount);+ $this->info(' - Payment not successful: ' . ($stats['payment_not_successful_count'] ?? 0));+ $this->info(' - Refunded / fully credited: ' . ($stats['refunded_invoices_count'] ?? 0));+ $this->info(' - Missing required data: ' . ($stats['missing_data_invoices_count'] ?? 0));+ $this->info(' - Defaulted to France: ' . ($stats['defaulted_to_fr_count'] ?? 0));// Display volume metrics+ $grossVolumeUsd = array_sum(array_column($processedInvoices, 'total_usd'));+ $netVolumeUsd = array_sum(array_column($processedInvoices, 'total_after_tax_usd'));+ $taxTotalUsd = array_sum(array_column($processedInvoices, 'tax_total_usd'));+ $grossVolumeEur = array_sum(array_column($processedInvoices, 'total_eur'));+ $netVolumeEur = array_sum(array_column($processedInvoices, 'total_after_tax_eur'));+ $taxTotalEur = array_sum(array_column($processedInvoices, 'tax_total_eur'));+$this->line('');$this->info('Volume Metrics (USD):');$this->info(' - Gross volume: $' . number_format($grossVolumeUsd, 2));@@ -279,6 +173,7 @@ class GenerateTaxExport extends Command'total_eur' => 0,'tax_total_eur' => 0,'total_after_tax_eur' => 0,+ 'stripe_fee_eur' => 0,];$aggregatedReport[$country] = ['individual' => $defaultVal,@@ -289,6 +184,7 @@ class GenerateTaxExport extends Command$aggregatedReport[$country][$customerType]['total_usd'] = ($aggregatedReport[$country][$customerType]['total_usd'] ?? 0) + $invoice['total_usd'];$aggregatedReport[$country][$customerType]['tax_total_usd'] = ($aggregatedReport[$country][$customerType]['tax_total_usd'] ?? 0) + $invoice['tax_total_usd'];$aggregatedReport[$country][$customerType]['total_after_tax_usd'] = ($aggregatedReport[$country][$customerType]['total_after_tax_usd'] ?? 0) + $invoice['total_after_tax_usd'];+ $aggregatedReport[$country][$customerType]['stripe_fee_eur'] = ($aggregatedReport[$country][$customerType]['stripe_fee_eur'] ?? 0) + $invoice['stripe_fee_eur'];$aggregatedReport[$country][$customerType]['total_eur'] = ($aggregatedReport[$country][$customerType]['total_eur'] ?? 0) + $invoice['total_eur'];$aggregatedReport[$country][$customerType]['tax_total_eur'] = ($aggregatedReport[$country][$customerType]['tax_total_eur'] ?? 0) + $invoice['tax_total_eur'];$aggregatedReport[$country][$customerType]['total_after_tax_eur'] = ($aggregatedReport[$country][$customerType]['total_after_tax_eur'] ?? 0) + $invoice['total_after_tax_eur'];@@ -361,18 +257,22 @@ class GenerateTaxExport extends Command$taxRate = $this->computeTaxRate($country, $vatId);- // Safely calculate tax amounts- $total = $invoice->total ?? 0;- $taxAmountCollectedUsd = $taxRate > 0 ? $total * $taxRate / ($taxRate + 100) : 0;+ $grossAmountUsd = (int) ($invoice->total ?? 0);+ $refundAmountUsd = $this->getInvoiceRefundAmount($invoice);+ $creditNotesAmountUsd = $this->getInvoiceCreditNotesAmount($invoice);+ $caNetUsd = $this->getNetInvoiceAmount($invoice);+ $taxAmountCollectedUsd = $taxRate > 0 ? $caNetUsd * $taxRate / ($taxRate + 100) : 0;- $totalEur = 0;+ $grossAmountEur = 0;+ $stripeFeeEur = 0;if (isset($invoice->charge) && isset($invoice->charge->balance_transaction)) {// Fast path: invoice has embedded charge (OpnForm-style accounts)$bt = $invoice->charge->balance_transaction;// balance_transaction->amount is NET (after fees), add fees back to get GROSS$netEur = $bt->amount ?? 0;$feeEur = $bt->fee ?? 0;- $totalEur = $netEur + $feeEur; // GROSS = NET + fees+ $grossAmountEur = $netEur + $feeEur; // GROSS = NET + fees+ $stripeFeeEur = $feeEur;} else {// Fallback: Stripe no longer embeds charge on invoice// Fetch the Charge explicitly by invoice ID, then read its balance_transaction@@ -390,18 +290,23 @@ class GenerateTaxExport extends Command// balance_transaction->amount is NET (after fees), add fees back to get GROSS$netEur = $bt->amount ?? 0;$feeEur = $bt->fee ?? 0;- $totalEur = $netEur + $feeEur; // GROSS = NET + fees+ $grossAmountEur = $netEur + $feeEur; // GROSS = NET + fees+ $stripeFeeEur = $feeEur;}} catch (\Exception $e) {// Silently continue if charge retrieval fails - EUR will remain 0}}+ $caNetEur = $this->applyInvoiceAdjustmentsToGrossAmount($invoice, $grossAmountEur);+ $refundAmountEur = $this->applyPartialInvoiceAdjustmentsToGrossAmount($invoice, $grossAmountEur, $refundAmountUsd);+ $creditNotesAmountEur = $this->applyPartialInvoiceAdjustmentsToGrossAmount($invoice, $grossAmountEur, $creditNotesAmountUsd);+ $stripeFeeNetEur = $this->applyPartialInvoiceAdjustmentsToGrossAmount($invoice, $grossAmountEur, $stripeFeeEur);+// Note: We calculate GROSS EUR (NET + fees) to match Stripe Dashboard// balance_transaction->amount = NET, balance_transaction->fee = Stripe fees- $taxAmountCollectedEur = $taxRate > 0 ? $totalEur * $taxRate / ($taxRate + 100) : 0;-+ $taxAmountCollectedEur = $taxRate > 0 ? $caNetEur * $taxRate / ($taxRate + 100) : 0;return ['invoice_id' => $invoice->id,'created_at' => Carbon::createFromTimestamp($invoice->created)->format('Y-m-d H:i:s'),@@ -409,12 +314,13 @@ class GenerateTaxExport extends Command'cust_vat_id' => $vatId,'cust_country' => $country,'tax_rate' => $taxRate,- 'total_usd' => $total / 100,+ 'total_usd' => $caNetUsd / 100,'tax_total_usd' => $taxAmountCollectedUsd / 100,- 'total_after_tax_usd' => ($total - $taxAmountCollectedUsd) / 100,- 'total_eur' => $totalEur / 100,+ 'total_after_tax_usd' => ($caNetUsd - $taxAmountCollectedUsd) / 100,+ 'total_eur' => $caNetEur / 100,'tax_total_eur' => $taxAmountCollectedEur / 100,- 'total_after_tax_eur' => ($totalEur - $taxAmountCollectedEur) / 100,+ 'total_after_tax_eur' => ($caNetEur - $taxAmountCollectedEur) / 100,+ 'stripe_fee_eur' => $stripeFeeNetEur / 100,'_defaulted_to_fr' => $defaultedToFrance,];}@@ -440,6 +346,179 @@ class GenerateTaxExport extends Commandreturn 0;}+ private function getInvoiceRefundAmount(Invoice $invoice): int+ {+ $invoiceRefundAmount = (int) ($invoice->amount_refunded ?? 0);+ $chargeRefundAmount = 0;++ if (isset($invoice->charge)) {+ $chargeRefundAmount = (int) ($invoice->charge->amount_refunded ?? 0);++ if ($chargeRefundAmount === 0 && isset($invoice->charge->refunded) && $invoice->charge->refunded) {+ $chargeRefundAmount = (int) ($invoice->total ?? 0);+ }+ }++ return max($invoiceRefundAmount, $chargeRefundAmount);+ }++ private function getInvoiceCreditNotesAmount(Invoice $invoice): int+ {+ return (int) (($invoice->post_payment_credit_notes_amount ?? 0) + ($invoice->pre_payment_credit_notes_amount ?? 0));+ }++ private function getNetInvoiceAmount(Invoice $invoice): int+ {+ return (int) (($invoice->total ?? 0) - $this->getInvoiceRefundAmount($invoice) - $this->getInvoiceCreditNotesAmount($invoice));+ }++ private function applyInvoiceAdjustmentsToGrossAmount(Invoice $invoice, int $grossAmount): int+ {+ $originalAmount = (int) ($invoice->total ?? 0);+ $netAmount = $this->getNetInvoiceAmount($invoice);++ if ($originalAmount === 0 || $grossAmount === 0 || $netAmount === $originalAmount) {+ return $grossAmount;+ }++ return (int) round($grossAmount * ($netAmount / $originalAmount));+ }++ private function applyPartialInvoiceAdjustmentsToGrossAmount(Invoice $invoice, int $grossAmount, int $partialAmount): int+ {+ $originalAmount = (int) ($invoice->total ?? 0);++ if ($originalAmount === 0 || $grossAmount === 0 || $partialAmount === 0) {+ return 0;+ }++ return (int) round($grossAmount * ($partialAmount / $originalAmount));+ }++ private function getBalanceTransactionSummary(string $startDate, string $endDate): array+ {+ $queryOptions = [+ 'limit' => 100,+ 'created' => [+ 'gte' => Carbon::parse($startDate)->startOfDay()->timestamp,+ 'lte' => Carbon::parse($endDate)->endOfDay()->timestamp,+ ],+ ];++ $transactions = Cashier::stripe()->balanceTransactions->all($queryOptions);+ $rows = [];++ do {+ foreach ($transactions as $transaction) {+ $rows[] = $transaction;+ }++ if (empty($transactions->data) || !$transactions->has_more) {+ break;+ }++ $queryOptions['starting_after'] = end($transactions->data)->id;+ $transactions = Cashier::stripe()->balanceTransactions->all($queryOptions);+ } while (true);++ $grossCollected = 0;+ $refunds = 0;+ $stripeFees = 0;+ $adjustments = 0;+ $netMovement = 0;+ $payouts = 0;++ foreach ($rows as $transaction) {+ $type = $transaction->type ?? '';+ $amount = (int) ($transaction->amount ?? 0);+ $fee = (int) ($transaction->fee ?? 0);+ $net = (int) ($transaction->net ?? 0);++ if (in_array($type, ['charge', 'payment'], true)) {+ $grossCollected += max(0, $amount);+ $stripeFees += $fee;+ $netMovement += $net;+ continue;+ }++ if (in_array($type, ['refund', 'payment_refund'], true)) {+ $refunds += abs($amount);+ $stripeFees += $fee;+ $netMovement += $net;+ continue;+ }++ if ($type === 'stripe_fee') {+ $stripeFees += abs($amount);+ $netMovement += $net;+ continue;+ }++ if ($type === 'adjustment') {+ $adjustments += $net;+ $stripeFees += $fee;+ $netMovement += $net;+ continue;+ }++ if ($type === 'payout') {+ $payouts += abs($amount);+ }+ }++ return [+ 'cash_gross_collected_eur' => $grossCollected / 100,+ 'cash_refunds_eur' => $refunds / 100,+ 'cash_stripe_fees_eur' => $stripeFees / 100,+ 'cash_adjustments_eur' => $adjustments / 100,+ 'cash_net_movement_eur' => $netMovement / 100,+ 'payouts_eur' => $payouts / 100,+ ];+ }++ private function appendReconciliationRows(array $aggregatedReport, array $summary): array+ {+ foreach ([+ 'cash_gross_collected' => 'cash_gross_collected_eur',+ 'cash_refunds' => 'cash_refunds_eur',+ 'cash_stripe_fees' => 'cash_stripe_fees_eur',+ 'cash_adjustments' => 'cash_adjustments_eur',+ 'cash_net_movement' => 'cash_net_movement_eur',+ 'payouts' => 'payouts_eur',+ ] as $label => $targetColumn) {+ $aggregatedReport[] = [+ 'country' => '__RECONCILIATION__',+ 'customer_type' => $label,+ 'count' => 0,+ 'gross_total_usd' => 0,+ 'refund_amount_usd' => 0,+ 'credit_notes_amount_usd' => 0,+ 'ca_net_usd' => 0,+ 'total_usd' => 0,+ 'tax_total_usd' => 0,+ 'total_after_tax_usd' => 0,+ 'gross_total_eur' => 0,+ 'refund_amount_eur' => 0,+ 'credit_notes_amount_eur' => 0,+ 'ca_net_eur' => 0,+ 'stripe_fee_eur' => 0,+ 'ca_net_after_stripe_fees_eur' => 0,+ 'cash_gross_collected_eur' => 0,+ 'cash_refunds_eur' => 0,+ 'cash_stripe_fees_eur' => 0,+ 'cash_adjustments_eur' => 0,+ 'cash_net_movement_eur' => 0,+ 'payouts_eur' => 0,+ 'total_eur' => 0,+ 'tax_total_eur' => 0,+ 'total_after_tax_eur' => 0,+ $targetColumn => $summary[$targetColumn],+ ];+ }++ return $aggregatedReport;+ }+private function isEuropeanCountry($countryCode){return isset(self::EU_TAX_RATES[$countryCode]);diff --git a/api/app/Services/Tax/StripeExportDatasetService.php b/api/app/Services/Tax/StripeExportDatasetService.phpnew file mode 100644index 000000000..7868b4366--- /dev/null+++ b/api/app/Services/Tax/StripeExportDatasetService.php@@ -0,0 +1,361 @@+<?php++namespace App\Services\Tax;++use Carbon\Carbon;+use Laravel\Cashier\Cashier;+use Stripe\Invoice;++class StripeExportDatasetService+{+ public const EU_TAX_RATES = [+ 'AT' => 20,+ 'BE' => 21,+ 'BG' => 20,+ 'HR' => 25,+ 'CY' => 19,+ 'CZ' => 21,+ 'DK' => 25,+ 'EE' => 22,+ 'FI' => 25.5,+ 'FR' => 20,+ 'DE' => 19,+ 'GR' => 24,+ 'HU' => 27,+ 'IE' => 23,+ 'IT' => 22,+ 'LV' => 21,+ 'LT' => 21,+ 'LU' => 17,+ 'MT' => 18,+ 'NL' => 21,+ 'PL' => 23,+ 'PT' => 23,+ 'RO' => 19,+ 'SK' => 20,+ 'SI' => 22,+ 'ES' => 21,+ 'SE' => 25,+ ];++ public function collect(string $startDate, string $endDate, ?callable $onInvoiceProcessed = null): array+ {+ $processedInvoices = [];+ $stats = [+ 'payment_not_successful_count' => 0,+ 'refunded_invoices_count' => 0,+ 'missing_data_invoices_count' => 0,+ 'total_invoice' => 0,+ 'processed_invoice_count' => 0,+ 'defaulted_to_fr_count' => 0,+ ];++ $queryOptions = [+ 'limit' => 100,+ 'expand' => [+ 'data.customer',+ 'data.customer.address',+ 'data.customer.tax_ids',+ 'data.payment_intent',+ 'data.payment_intent.payment_method',+ 'data.payment_intent.latest_charge.balance_transaction',+ 'data.charge.balance_transaction',+ 'data.automatic_tax',+ 'data.total_tax_amounts.tax_rate',+ ],+ 'status' => 'paid',+ 'created' => [+ 'gte' => Carbon::parse($startDate)->startOfDay()->timestamp,+ 'lte' => Carbon::parse($endDate)->endOfDay()->timestamp,+ ],+ ];++ $invoices = Cashier::stripe()->invoices->all($queryOptions);++ do {+ if (empty($invoices->data)) {+ break;+ }++ foreach ($invoices as $invoice) {+ $stats['total_invoice']++;++ $invoiceStatus = $invoice->status ?? null;+ $paymentIntentStatus = $invoice->payment_intent->status ?? null;++ if ($invoiceStatus !== 'paid' && $paymentIntentStatus !== 'succeeded') {+ $stats['payment_not_successful_count']++;+ continue;+ }++ $netInvoiceAmount = $this->getNetInvoiceAmount($invoice);+ if (($invoice->total ?? 0) > 0 && $netInvoiceAmount <= 0) {+ $stats['refunded_invoices_count']++;+ continue;+ }++ try {+ $row = $this->formatDatasetRow($invoice);+ if (($row['_defaulted_to_fr'] ?? false) === true) {+ $stats['defaulted_to_fr_count']++;+ }+ $processedInvoices[] = $row;+ $stats['processed_invoice_count']++;++ if ($onInvoiceProcessed) {+ $onInvoiceProcessed($stats, $row);+ }+ } catch (\Throwable $e) {+ $stats['missing_data_invoices_count']++;+ }+ }++ if (empty($invoices->data) || !$invoices->has_more) {+ break;+ }++ $queryOptions['starting_after'] = end($invoices->data)->id;+ $invoices = Cashier::stripe()->invoices->all($queryOptions);+ } while (true);++ return [+ 'rows' => $processedInvoices,+ 'stats' => $stats,+ ];+ }++ public function toTaxExportRow(array $row): array+ {+ return [+ 'invoice_id' => $row['invoice_id'],+ 'created_at' => $row['created_at'],+ 'cust_id' => $row['cust_id'],+ 'cust_vat_id' => $row['cust_vat_id'],+ 'cust_country' => $row['cust_country'],+ 'tax_rate' => $row['tax_rate'],+ 'customer_type' => $row['customer_type'],+ 'total_usd' => $row['total_usd'],+ 'tax_total_usd' => $row['tax_total_usd'],+ 'total_after_tax_usd' => $row['total_after_tax_usd'],+ 'total_eur' => $row['total_eur'],+ 'tax_total_eur' => $row['tax_total_eur'],+ 'total_after_tax_eur' => $row['total_after_tax_eur'],+ 'stripe_fee_eur' => $row['stripe_fee_eur'],+ ];+ }++ private function formatDatasetRow(Invoice $invoice): array+ {+ [$country, $defaultedToFrance] = $this->resolveCountry($invoice);+ $vatId = $this->extractVatId($invoice);+ $cleanVatId = $vatId ? $this->cleanVatNumber($vatId) : null;+ $taxRate = $this->computeTaxRate($country, $cleanVatId);++ $caNetUsd = $this->getNetInvoiceAmount($invoice);+ $taxAmountCollectedUsd = $taxRate > 0 ? $caNetUsd * $taxRate / ($taxRate + 100) : 0;++ [$grossAmountEur, $stripeFeeEur] = $this->resolveGrossAmountAndFeeEur($invoice);+ $caNetEur = $this->applyInvoiceAdjustmentsToGrossAmount($invoice, $grossAmountEur);+ $taxAmountCollectedEur = $taxRate > 0 ? $caNetEur * $taxRate / ($taxRate + 100) : 0;++ $customerType = is_null($cleanVatId) && $this->isEuropeanCountry($country) ? 'individual' : 'business';+ $desEligible = $this->isEligibleForDes($country, $cleanVatId);+ $createdAt = Carbon::createFromTimestamp($invoice->created);++ return [+ 'invoice_id' => $invoice->id,+ 'created_at' => $createdAt->format('Y-m-d H:i:s'),+ 'created_ts' => $invoice->created,+ 'cust_id' => $invoice->customer->id ?? 'unknown',+ 'cust_vat_id' => $cleanVatId,+ 'cust_country' => $country,+ 'customer_type' => $customerType,+ 'tax_rate' => $taxRate,+ 'total_usd' => $caNetUsd / 100,+ 'tax_total_usd' => $taxAmountCollectedUsd / 100,+ 'total_after_tax_usd' => ($caNetUsd - $taxAmountCollectedUsd) / 100,+ 'total_eur' => $caNetEur / 100,+ 'tax_total_eur' => $taxAmountCollectedEur / 100,+ 'total_after_tax_eur' => ($caNetEur - $taxAmountCollectedEur) / 100,+ 'stripe_fee_eur' => $this->applyPartialInvoiceAdjustmentsToGrossAmount($invoice, $grossAmountEur, $stripeFeeEur) / 100,+ 'des_eligible' => $desEligible,+ 'des_country_code' => $country,+ 'des_vat_number' => $cleanVatId,+ 'des_amount_eur' => ($caNetEur - $taxAmountCollectedEur) / 100,+ '_defaulted_to_fr' => $defaultedToFrance,+ ];+ }++ private function resolveCountry(Invoice $invoice): array+ {+ if (!empty($invoice->customer->address->country)) {+ return [$invoice->customer->address->country, false];+ }++ foreach (($invoice->total_tax_amounts ?? []) as $taxAmount) {+ $taxRateCountry = $taxAmount->tax_rate->country ?? null;+ if (!empty($taxRateCountry)) {+ return [$taxRateCountry, false];+ }+ }++ $autoTaxCountry = $invoice->automatic_tax->tax_location->country ?? null;+ if (!empty($autoTaxCountry)) {+ return [$autoTaxCountry, false];+ }++ foreach (($invoice->customer->tax_ids->data ?? []) as $taxId) {+ if (!empty($taxId->country)) {+ return [$taxId->country, false];+ }+ }++ $paymentCountry = $invoice->payment_intent->payment_method->card->country ?? null;+ if (!empty($paymentCountry)) {+ return [$paymentCountry, false];+ }++ return ['FR', true];+ }++ private function resolveGrossAmountAndFeeEur(Invoice $invoice): array+ {+ if (isset($invoice->charge) && isset($invoice->charge->balance_transaction)) {+ $netEur = $invoice->charge->balance_transaction->amount ?? 0;+ $feeEur = $invoice->charge->balance_transaction->fee ?? 0;++ return [$netEur + $feeEur, $feeEur];+ }++ if (isset($invoice->payment_intent->latest_charge) && isset($invoice->payment_intent->latest_charge->balance_transaction)) {+ $netEur = $invoice->payment_intent->latest_charge->balance_transaction->amount ?? 0;+ $feeEur = $invoice->payment_intent->latest_charge->balance_transaction->fee ?? 0;++ return [$netEur + $feeEur, $feeEur];+ }++ foreach (($invoice->payment_intent->charges->data ?? []) as $charge) {+ if (isset($charge->balance_transaction)) {+ $netEur = $charge->balance_transaction->amount ?? 0;+ $feeEur = $charge->balance_transaction->fee ?? 0;++ return [$netEur + $feeEur, $feeEur];+ }+ }++ try {+ $charges = Cashier::stripe()->charges->all([+ 'invoice' => $invoice->id,+ 'limit' => 1,+ 'expand' => ['data.balance_transaction'],+ ]);++ $charge = $charges->data[0] ?? null;+ if ($charge && isset($charge->balance_transaction)) {+ $netEur = $charge->balance_transaction->amount ?? 0;+ $feeEur = $charge->balance_transaction->fee ?? 0;++ return [$netEur + $feeEur, $feeEur];+ }+ } catch (\Throwable $e) {+ }++ if (($invoice->currency ?? null) === 'eur') {+ return [(int) ($invoice->total ?? 0), 0];+ }++ throw new \RuntimeException("Could not resolve EUR amount for invoice {$invoice->id}");+ }++ private function extractVatId(Invoice $invoice): ?string+ {+ foreach (($invoice->customer->tax_ids->data ?? []) as $taxId) {+ if (!empty($taxId->value)) {+ return $taxId->value;+ }+ }++ return null;+ }++ private function isEligibleForDes(?string $country, ?string $vatId): bool+ {+ if (!$country || $country === 'FR' || !$this->isEuropeanCountry($country) || !$vatId) {+ return false;+ }++ return str_starts_with($vatId, $country);+ }++ private function cleanVatNumber(string $vatId): string+ {+ return strtoupper(str_replace(['.', '-', ' '], '', $vatId));+ }++ private function isEuropeanCountry(?string $countryCode): bool+ {+ return isset(self::EU_TAX_RATES[$countryCode]);+ }++ private function computeTaxRate(?string $countryCode, ?string $vatId): float|int+ {+ if ($countryCode === 'FR' || empty($countryCode)) {+ return 20;+ }++ if ($vatId) {+ return 0;+ }++ return self::EU_TAX_RATES[$countryCode] ?? 0;+ }++ private function getInvoiceRefundAmount(Invoice $invoice): int+ {+ $invoiceRefundAmount = (int) ($invoice->amount_refunded ?? 0);+ $chargeRefundAmount = 0;++ if (isset($invoice->charge)) {+ $chargeRefundAmount = (int) ($invoice->charge->amount_refunded ?? 0);++ if ($chargeRefundAmount === 0 && isset($invoice->charge->refunded) && $invoice->charge->refunded) {+ $chargeRefundAmount = (int) ($invoice->total ?? 0);+ }+ }++ return max($invoiceRefundAmount, $chargeRefundAmount);+ }++ private function getInvoiceCreditNotesAmount(Invoice $invoice): int+ {+ return (int) (($invoice->post_payment_credit_notes_amount ?? 0) + ($invoice->pre_payment_credit_notes_amount ?? 0));+ }++ private function getNetInvoiceAmount(Invoice $invoice): int+ {+ return (int) (($invoice->total ?? 0) - $this->getInvoiceRefundAmount($invoice) - $this->getInvoiceCreditNotesAmount($invoice));+ }++ private function applyInvoiceAdjustmentsToGrossAmount(Invoice $invoice, int|float $grossAmount): int+ {+ $originalAmount = (int) ($invoice->total ?? 0);+ $netAmount = $this->getNetInvoiceAmount($invoice);++ if ($originalAmount === 0 || $grossAmount == 0.0 || $netAmount === $originalAmount) {+ return (int) round($grossAmount);+ }++ return (int) round($grossAmount * ($netAmount / $originalAmount));+ }++ private function applyPartialInvoiceAdjustmentsToGrossAmount(Invoice $invoice, int|float $grossAmount, int|float $partialAmount): int+ {+ $originalAmount = (int) ($invoice->total ?? 0);++ if ($originalAmount === 0 || $grossAmount == 0.0 || $partialAmount == 0.0) {+ return 0;+ }++ return (int) round($grossAmount * ($partialAmount / $originalAmount));+ }+}diff --git a/api/app/Services/Tax/StripeExportDatasetStore.php b/api/app/Services/Tax/StripeExportDatasetStore.phpnew file mode 100644index 000000000..5464ca449--- /dev/null+++ b/api/app/Services/Tax/StripeExportDatasetStore.php@@ -0,0 +1,120 @@+<?php++namespace App\Services\Tax;++class StripeExportDatasetStore+{+ public function basePath(): string+ {+ return storage_path('app/stripe-export-datasets');+ }++ public function datasetPath(string $datasetId): string+ {+ return $this->basePath() . '/' . $datasetId;+ }++ public function metadataPath(string $datasetId): string+ {+ return $this->datasetPath($datasetId) . '/metadata.json';+ }++ public function datasetRowsPath(string $datasetId): string+ {+ return $this->datasetPath($datasetId) . '/dataset.json';+ }++ public function chunksPath(string $datasetId): string+ {+ return $this->datasetPath($datasetId) . '/chunks';+ }++ public function chunkPath(string $datasetId, string $chunkKey): string+ {+ return $this->chunksPath($datasetId) . '/' . $chunkKey . '.json';+ }++ public function initialize(string $datasetId, array $metadata = []): void+ {+ if (!is_dir($this->chunksPath($datasetId))) {+ mkdir($this->chunksPath($datasetId), 0777, true);+ }++ $this->writeJson($this->metadataPath($datasetId), array_merge([+ 'dataset_id' => $datasetId,+ 'status' => 'initialized',+ 'created_at' => now()->toIso8601String(),+ ], $metadata));+ }++ public function writeChunk(string $datasetId, string $chunkKey, array $rows, array $stats = []): void+ {+ $this->writeJson($this->chunkPath($datasetId, $chunkKey), [+ 'chunk_key' => $chunkKey,+ 'row_count' => count($rows),+ 'stats' => $stats,+ 'rows' => $rows,+ ]);+ }++ public function mergeChunks(string $datasetId): array+ {+ $files = glob($this->chunksPath($datasetId) . '/*.json') ?: [];+ sort($files);++ $rows = [];+ $chunkSummaries = [];++ foreach ($files as $file) {+ $payload = $this->readJson($file);+ $rows = array_merge($rows, $payload['rows'] ?? []);+ $chunkSummaries[] = [+ 'chunk_key' => $payload['chunk_key'] ?? basename($file, '.json'),+ 'row_count' => $payload['row_count'] ?? count($payload['rows'] ?? []),+ 'stats' => $payload['stats'] ?? [],+ ];+ }++ usort($rows, function (array $left, array $right) {+ return [$left['created_ts'] ?? 0, $left['invoice_id'] ?? ''] <=> [$right['created_ts'] ?? 0, $right['invoice_id'] ?? ''];+ });++ $this->writeJson($this->datasetRowsPath($datasetId), $rows);++ $metadata = $this->readMetadata($datasetId);+ $metadata['status'] = 'completed';+ $metadata['completed_at'] = now()->toIso8601String();+ $metadata['row_count'] = count($rows);+ $metadata['chunks'] = $chunkSummaries;+ $this->writeJson($this->metadataPath($datasetId), $metadata);++ return $rows;+ }++ public function loadRows(string $datasetId): array+ {+ $path = $this->datasetRowsPath($datasetId);+ if (!file_exists($path)) {+ return $this->mergeChunks($datasetId);+ }++ return $this->readJson($path);+ }++ public function readMetadata(string $datasetId): array+ {+ $path = $this->metadataPath($datasetId);++ return file_exists($path) ? $this->readJson($path) : [];+ }++ private function writeJson(string $path, array $payload): void+ {+ file_put_contents($path, json_encode($payload, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES));+ }++ private function readJson(string $path): array+ {+ return json_decode(file_get_contents($path), true, 512, JSON_THROW_ON_ERROR);+ }+}