Adds DB facade macro for transaction retries

Introduces a `DB::transactionWithRetry` macro to the DB facade and connection instances.

This allows for easier and more readable integration of transaction retry logic directly through the database facade, simplifying existing transaction code.

Includes documentation updates and necessary service provider registration.

Author: Ahed92Wakim

.php-cs-fixer.cache

@@ -1 +1 @@
-{"php":"8.2.29","version":"3.89.0:v3.89.0#4dd6768cb7558440d27d18f54909eee417317ce9","indent":"    ","lineEnding":"\n","rules":{"binary_operator_spaces":{"default":"align_single_space_minimal"},"blank_line_after_opening_tag":true,"blank_line_between_import_groups":true,"blank_lines_before_namespace":true,"braces_position":{"allow_single_line_empty_anonymous_classes":true},"class_definition":{"inline_constructor_arguments":false,"space_before_parenthesis":true},"compact_nullable_type_declaration":true,"declare_equal_normalize":true,"lowercase_cast":true,"lowercase_static_reference":true,"modifier_keywords":true,"new_with_parentheses":{"anonymous_class":true},"no_blank_lines_after_class_opening":true,"no_extra_blank_lines":true,"no_leading_import_slash":true,"no_whitespace_in_blank_line":true,"ordered_class_elements":{"order":["use_trait"]},"ordered_imports":{"sort_algorithm":"alpha"},"return_type_declaration":true,"short_scalar_cast":true,"single_import_per_statement":{"group_to_single_imports":false},"single_space_around_construct":{"constructs_followed_by_a_single_space":["abstract","as","case","catch","class","const_import","do","else","elseif","final","finally","for","foreach","function","function_import","if","insteadof","interface","namespace","new","private","protected","public","static","switch","trait","try","use","use_lambda","while"],"constructs_preceded_by_a_single_space":["as","else","elseif","use_lambda"]},"single_trait_insert_per_statement":true,"ternary_operator_spaces":true,"unary_operator_spaces":{"only_dec_inc":true},"blank_line_after_namespace":true,"constant_case":true,"control_structure_braces":true,"control_structure_continuation_position":true,"elseif":true,"function_declaration":{"closure_fn_spacing":"one"},"indentation_type":true,"line_ending":true,"lowercase_keywords":true,"method_argument_space":{"after_heredoc":false,"attribute_placement":"ignore","on_multiline":"ensure_fully_multiline"},"no_break_comment":true,"no_closing_tag":true,"no_multiple_statements_per_line":true,"no_space_around_double_colon":true,"no_spaces_after_function_name":true,"no_trailing_whitespace":true,"no_trailing_whitespace_in_comment":true,"single_blank_line_at_eof":true,"single_class_element_per_statement":{"elements":["property"]},"single_line_after_imports":true,"spaces_inside_parentheses":true,"statement_indentation":true,"switch_case_semicolon_to_colon":true,"switch_case_space":true,"encoding":true,"full_opening_tag":true,"array_syntax":{"syntax":"short"},"single_quote":true,"no_unused_imports":true,"no_superfluous_phpdoc_tags":true,"phpdoc_trim":true,"phpdoc_align":{"align":"left"},"blank_line_before_statement":{"statements":["return"]},"simplified_null_return":true,"void_return":true},"hashes":{"tests\/Unit\/DBTransactionRetryHelperTest.php":"27f37268e9ae100d356ca1c06c756616","tests\/Feature\/ExampleTest.php":"a1e5352ea369ad36f88f4f566c340371","tests\/Pest.php":"44a41307b2bca2c9b747aa2f40c5262b","tests\/bootstrap.php":"4ae74313e457f6662f4831ee2140eb34","src\/Console\/StartRetryCommand.php":"b0e6c76186a59d1341fa6600e096f9a3","src\/Console\/StopRetryCommand.php":"ad3d7cbb9841006db54f12168c58d369","src\/Providers\/DatabaseTransactionRetryServiceProvider.php":"638c2f84c78a86c8e8c5e4daef07c46e","src\/Services\/TransactionRetrier.php":"504c45ab8315c7b3d60a64e0a52759af","src\/Support\/RetryToggle.php":"2516f4c290940019b1f1c069fec64be8","src\/Support\/BindingStringifier.php":"bbead2bae37761124652320cd28db412","src\/Support\/TransactionRetryLogWriter.php":"2bc60103437973d7b471ad6bc91c43cf","src\/Support\/TraceFormatter.php":"e640e32b17149f1cfec9a1d990f04c84","tests\/TestCase.php":"897cfbd81822f4b71075ccb1739df70d","tests\/Unit\/ExampleTest.php":"3bbd4ea8029698f723c35a66d8592087"}}
+{"php":"8.2.29","version":"3.89.0:v3.89.0#4dd6768cb7558440d27d18f54909eee417317ce9","indent":"    ","lineEnding":"\n","rules":{"binary_operator_spaces":{"default":"align_single_space_minimal"},"blank_line_after_opening_tag":true,"blank_line_between_import_groups":true,"blank_lines_before_namespace":true,"braces_position":{"allow_single_line_empty_anonymous_classes":true},"class_definition":{"inline_constructor_arguments":false,"space_before_parenthesis":true},"compact_nullable_type_declaration":true,"declare_equal_normalize":true,"lowercase_cast":true,"lowercase_static_reference":true,"modifier_keywords":true,"new_with_parentheses":{"anonymous_class":true},"no_blank_lines_after_class_opening":true,"no_extra_blank_lines":true,"no_leading_import_slash":true,"no_whitespace_in_blank_line":true,"ordered_class_elements":{"order":["use_trait"]},"ordered_imports":{"sort_algorithm":"alpha"},"return_type_declaration":true,"short_scalar_cast":true,"single_import_per_statement":{"group_to_single_imports":false},"single_space_around_construct":{"constructs_followed_by_a_single_space":["abstract","as","case","catch","class","const_import","do","else","elseif","final","finally","for","foreach","function","function_import","if","insteadof","interface","namespace","new","private","protected","public","static","switch","trait","try","use","use_lambda","while"],"constructs_preceded_by_a_single_space":["as","else","elseif","use_lambda"]},"single_trait_insert_per_statement":true,"ternary_operator_spaces":true,"unary_operator_spaces":{"only_dec_inc":true},"blank_line_after_namespace":true,"constant_case":true,"control_structure_braces":true,"control_structure_continuation_position":true,"elseif":true,"function_declaration":{"closure_fn_spacing":"one"},"indentation_type":true,"line_ending":true,"lowercase_keywords":true,"method_argument_space":{"after_heredoc":false,"attribute_placement":"ignore","on_multiline":"ensure_fully_multiline"},"no_break_comment":true,"no_closing_tag":true,"no_multiple_statements_per_line":true,"no_space_around_double_colon":true,"no_spaces_after_function_name":true,"no_trailing_whitespace":true,"no_trailing_whitespace_in_comment":true,"single_blank_line_at_eof":true,"single_class_element_per_statement":{"elements":["property"]},"single_line_after_imports":true,"spaces_inside_parentheses":true,"statement_indentation":true,"switch_case_semicolon_to_colon":true,"switch_case_space":true,"encoding":true,"full_opening_tag":true,"array_syntax":{"syntax":"short"},"single_quote":true,"no_unused_imports":true,"no_superfluous_phpdoc_tags":true,"phpdoc_trim":true,"phpdoc_align":{"align":"left"},"blank_line_before_statement":{"statements":["return"]},"simplified_null_return":true,"void_return":true},"hashes":{"tests\/Unit\/DBTransactionRetryHelperTest.php":"22e94a33db107726ebdb9ab6c1794f38","tests\/Feature\/ExampleTest.php":"a1e5352ea369ad36f88f4f566c340371","tests\/Pest.php":"44a41307b2bca2c9b747aa2f40c5262b","tests\/bootstrap.php":"4ae74313e457f6662f4831ee2140eb34","src\/Console\/StartRetryCommand.php":"ebbff074a2e7d79f377ef520285c6109","src\/Console\/StopRetryCommand.php":"92a0540c45489bf3a6ba11c517b84699","src\/Providers\/DatabaseTransactionRetryServiceProvider.php":"a4ba3a51cad9c3a470246518bc1bf5a6","src\/Services\/TransactionRetrier.php":"504c45ab8315c7b3d60a64e0a52759af","src\/Support\/RetryToggle.php":"2516f4c290940019b1f1c069fec64be8","src\/Support\/BindingStringifier.php":"bbead2bae37761124652320cd28db412","src\/Support\/TransactionRetryLogWriter.php":"2bc60103437973d7b471ad6bc91c43cf","src\/Support\/TraceFormatter.php":"e640e32b17149f1cfec9a1d990f04c84","tests\/TestCase.php":"897cfbd81822f4b71075ccb1739df70d","tests\/Unit\/ExampleTest.php":"3bbd4ea8029698f723c35a66d8592087","src\/Providers\/DbMacroServiceProvider.php":"e17026a164c34320845575f00076938d"}}

README.md

@@ -27,6 +27,7 @@ Resilient database transactions for Laravel applications that need to gracefully
 - Structured logs with request metadata, SQL, bindings, connection information, and stack traces written to dated files under `storage/logs/{Y-m-d}`.
 - Log titles include the exception class and codes, making it easy to see exactly what triggered the retry.
 - Optional transaction labels and custom log file names for easier traceability across microservices and jobs.
+- Convenience `DB::transactionWithRetry` macro on both the facade and individual connections so existing transaction code stays readable.
 - Laravel package auto-discovery; no manual service provider registration required.
 
 ## Installation
@@ -58,6 +59,32 @@ $order = Retry::runWithRetry(
 
 `runWithRetry()` returns the value produced by your callback, just like `DB::transaction()`. If every attempt fails, the last exception is re-thrown so your calling code can continue its normal error handling.
 
+### DB Macro Convenience
+
+Prefer working through the database facade? Call the included `transactionWithRetry` macro and keep identical behaviour and parameters:
+
+```php
+$invoice = DB::transactionWithRetry(
+    function () use ($payload) {
+        return Invoice::fromPayload($payload);
+    },
+    maxRetries: 5,
+    retryDelay: 1,
+    trxLabel: 'invoice-sync'
+);
+```
+
+Need connection-specific logic? Because the macro is applied to `Illuminate\Support\Facades\DB` **and** to every resolved `Illuminate\Database\Connection`, you can call it on connection instances as well:
+
+```php
+$report = DB::connection('analytics')->transactionWithRetry(
+    fn () => $builder->lockForUpdate()->selectRaw('count(*) as total')->first(),
+    trxLabel: 'analytics-rollup'
+);
+```
+
+The macro is registered automatically when the service provider boots, and sets the `tx.label` container binding the same way as the helper.
+
 ### Parameters
 
 | Parameter     | Default                                   | Description                                                                                                         |

src/Providers/DatabaseTransactionRetryServiceProvider.php

@@ -14,6 +14,8 @@ public function register(): void
             __DIR__ . '/../../config/database-transaction-retry.php',
             'database-transaction-retry'
         );
+
+        $this->app->register(DbMacroServiceProvider::class);
     }
 
     /**

src/Providers/DbMacroServiceProvider.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace DatabaseTransactions\RetryHelper\Providers;
+
+use Closure;
+use DatabaseTransactions\RetryHelper\Services\TransactionRetrier;
+use Illuminate\Database\Connection;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\ServiceProvider;
+
+class DbMacroServiceProvider extends ServiceProvider
+{
+    public function register(): void
+    {
+        //
+    }
+
+    /**
+     * Bootstrap any package services.
+     */
+    public function boot(): void
+    {
+        $this->registerDbFacadeMacro();
+    }
+
+    protected function registerDbFacadeMacro(): void
+    {
+        $macro = function (
+            Closure $callback,
+            ?int $maxRetries = null,
+            ?int $retryDelay = null,
+            ?string $logFileName = null,
+            string $trxLabel = ''
+        ) {
+            return TransactionRetrier::runWithRetry(
+                $callback,
+                $maxRetries,
+                $retryDelay,
+                $logFileName,
+                $trxLabel
+            );
+        };
+
+        if (is_callable([DB::class, 'macro']) && ! DB::hasMacro('transactionWithRetry')) {
+            DB::macro('transactionWithRetry', $macro);
+        }
+
+        if (
+            method_exists(Connection::class, 'macro')
+            && method_exists(Connection::class, 'hasMacro')
+            && ! Connection::hasMacro('transactionWithRetry')
+        ) {
+            Connection::macro('transactionWithRetry', $macro);
+        }
+    }
+}

tests/Unit/DBTransactionRetryHelperTest.php

@@ -11,14 +11,19 @@ function sleep(int $seconds): void
 
 use DatabaseTransactions\RetryHelper\Console\StartRetryCommand;
 use DatabaseTransactions\RetryHelper\Console\StopRetryCommand;
+use DatabaseTransactions\RetryHelper\Providers\DbMacroServiceProvider;
 use DatabaseTransactions\RetryHelper\Services\TransactionRetrier;
 use DatabaseTransactions\RetryHelper\Support\RetryToggle;
 use Illuminate\Container\Container;
 use Illuminate\Database\QueryException;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Traits\Macroable;
 use Psr\Log\AbstractLogger;
 use Symfony\Component\Console\Tester\CommandTester;
 
 beforeEach(function (): void {
+    FakeDatabaseManager::flushMacros();
+
     $this->database   = new FakeDatabaseManager();
     $this->logManager = new FakeLogManager();
 
@@ -201,6 +206,26 @@ function sleep(int $seconds): void
     expect($record['context']['driverCode'])->toBe(1213);
 });
 
+test('db facade macro delegates to transaction retrier', function (): void {
+    $provider = new DbMacroServiceProvider($this->app);
+    $provider->boot();
+
+    $attempts = 0;
+
+    expect(FakeDatabaseManager::hasMacro('transactionWithRetry'))->toBeTrue();
+
+    $result = DB::transactionWithRetry(function () use (&$attempts) {
+        $attempts++;
+
+        return 'macro-done';
+    }, trxLabel: 'macro-test');
+
+    expect($result)->toBe('macro-done');
+    expect($attempts)->toBe(1);
+    expect($this->database->transactionCalls)->toBe(1);
+    expect($this->app->make('tx.label'))->toBe('macro-test');
+});
+
 test('does not retry for non deadlock query exception', function (): void {
     try {
         TransactionRetrier::runWithRetry(function (): void {
@@ -487,6 +512,8 @@ final class CustomRetryException extends \RuntimeException
 
 final class FakeDatabaseManager
 {
+    use Macroable;
+
     public int $transactionCalls = 0;
     /** @var list<array{0:string,1:array}> */
     public array $statementCalls = [];