Php Sdk Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require touchestate-sdk/php-sdk
   

   Add the SDK to your config/app.php providers (if using Laravel):

   'providers' => [
       // ...
       TouchEstate\SDK\TouchEstateServiceProvider::class,
   ],
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="TouchEstate\SDK\TouchEstateServiceProvider"
   

   Update .env with your API credentials:

   TOUCHESTATE_API_KEY=your_api_key_here
   TOUCHESTATE_API_SECRET=your_api_secret_here
   TOUCHESTATE_API_URL=https://api.touchestate.com/v1
   

3. First Use Case: Fetching a Property

   use TouchEstate\SDK\Facades\TouchEstate;
   
   $property = TouchEstate::property()->find(123);
   dd($property);
   

Key Entry Points

• Facade: TouchEstate::resource()->action() (e.g., property()->find()).
• Service Container: Bind the SDK to Laravel’s IoC via TouchEstateServiceProvider.
• API Docs: Check vendor/touchestate-sdk/php-sdk/src/Resources/ for request/response models.

Implementation Patterns

Common Workflows

1. CRUD Operations

Create a Property Listing

$property = TouchEstate::property()->create([
    'title' => 'Modern Apartment',
    'address' => '123 Main St',
    'price' => 500000,
    'bedrooms' => 2,
]);

Update a Listing

$updated = TouchEstate::property()->update(123, [
    'price' => 499000,
    'status' => 'pending',
]);

Delete a Listing

$deleted = TouchEstate::property()->delete(123);

2. Querying with Filters

$listings = TouchEstate::property()->query()
    ->where('price', '<', 300000)
    ->where('bedrooms', '>=', 2)
    ->limit(10)
    ->get();

3. Handling Media (Images/Videos)

// Upload an image
$media = TouchEstate::media()->upload('path/to/image.jpg', [
    'property_id' => 123,
    'type' => 'image',
]);

// Get media for a property
$images = TouchEstate::media()->forProperty(123)->get();

4. Webhooks & Events

Subscribe to property status changes:

$webhook = TouchEstate::webhook()->create([
    'url' => 'https://your-app.com/touchestate/webhook',
    'events' => ['property.updated', 'property.published'],
]);

5. Laravel Integration

Bind SDK to a Controller

use TouchEstate\SDK\Contracts\PropertyRepository;

class PropertyController extends Controller
{
    public function __construct(private PropertyRepository $propertyRepo) {}

    public function index()
    {
        $properties = $this->propertyRepo->all();
        return view('properties.index', compact('properties'));
    }
}

Handle API Exceptions Globally Override the exception handler in App\Exceptions\Handler.php:

public function register()
{
    $this->reportable(function (TouchEstateException $e) {
        // Log or notify
    });
}

Best Practices

1. Rate Limiting Implement exponential backoff for retries:

   TouchEstate::setRetryPolicy(new RetryPolicy(3, 500)); // 3 retries, 500ms delay
   

2. Caching Responses Cache frequent queries (e.g., property listings):

   $properties = Cache::remember('touchestate_properties', 3600, function () {
       return TouchEstate::property()->all();
   });
   

3. Testing Use the SDK’s mocking capabilities:

   $mock = Mockery::mock(TouchEstate::class);
   $mock->shouldReceive('property()->find')->andReturn($fakeProperty);
   

4. Logging Enable debug logging for API calls:

   TouchEstate::setDebug(true);
   

Gotchas and Tips

Pitfalls

1. Authentication Failures

   • Issue: 401 Unauthorized errors if TOUCHESTATE_API_KEY/SECRET are misconfigured.
   • Fix: Verify .env and regenerate keys in TouchEstate dashboard.
   • Debug: Enable debug mode to log the exact request payload:

     TouchEstate::setDebug(true);
     

2. Rate Limits

   • Issue: 429 Too Many Requests if exceeding API limits (default: 60 calls/minute).
   • Fix: Implement retry logic with delays:

     TouchEstate::setRetryPolicy(new RetryPolicy(5, 1000));
     

3. Data Validation

   • Issue: Silent failures if required fields (e.g., title, price) are missing.
   • Fix: Validate input before calling SDK methods:

     $validated = $request->validate([
         'title' => 'required|string',
         'price' => 'required|numeric',
     ]);
     

4. Webhook Delays

   • Issue: Webhook payloads may arrive out of order or delayed.
   • Fix: Use idempotency_keys in webhook payloads to handle duplicates.

5. Timezone Mismatches

   • Issue: API returns timestamps in UTC; Laravel may use a different timezone.
   • Fix: Normalize timestamps:

     $createdAt = $property->created_at->setTimezone('UTC');
     

Tips

1. Batch Operations Use bulk endpoints for efficiency:

   $updated = TouchEstate::property()->updateMany([
       123 => ['price' => 499000],
       456 => ['price' => 550000],
   ]);
   

2. Webhook Verification Verify incoming webhook signatures:

   use TouchEstate\SDK\WebhookVerifier;
   
   $verifier = new WebhookVerifier($request->header('X-Signature'));
   if (!$verifier->verify($request->getContent())) {
       abort(403);
   }
   

3. Environment-Specific Config Use Laravel’s config caching to avoid republishing configs:

   php artisan config:cache
   

4. SDK Extensions Extend the SDK for custom resources:

   // app/Providers/TouchEstateServiceProvider.php
   public function boot()
   {
       TouchEstate::extend('custom_resource', function ($app) {
           return new CustomResourceRepository();
       });
   }
   

5. Performance

   • Pagination: Use ->paginate(20) for large datasets.
   • Selective Fields: Fetch only needed fields:

     $property = TouchEstate::property()->find(123, ['id', 'title', 'price']);
     

6. Error Handling Catch specific exceptions:

   try {
       $property = TouchEstate::property()->find(123);
   } catch (PropertyNotFoundException $e) {
       abort(404);
   } catch (TouchEstateException $e) {
       Log::error($e->getMessage());
       abort(500);
   }
   

7. Local Development Use a local proxy (e.g., Laravel Valet) to mock API responses during development:

   // config/touchestate.php
   'url' => env('TOUCHESTATE_API_URL', 'http://touchestate.test'),
   

8. Documentation Gaps

   • Workaround: Inspect the SDK’s src/Requests/ and src/Resources/ directories for undocumented endpoints.
   • Example: Check PropertyRequest.php for available query parameters.

9. Idempotency Use idempotency keys for safe retries:

   $property = TouchEstate::property()->create($data, [
       'idempotency_key' => 'unique_key_123',
   ]);
   

10. Testing Webhooks Use the SDK’s webhook testing endpoint:

    $testResponse = TouchEstate::webhook()->test('property.updated', $payload);