Download the PHP package tapbuy/checkout-graphql without Composer

Tapbuy CheckoutGraphql Module

A Magento 2 GraphQL extension that provides enhanced checkout functionality with token-based authorization for secure access to customer, order, and payment data.

Overview

The Tapbuy CheckoutGraphql module extends Magento 2's native GraphQL API with additional resolvers and functionality specifically designed for checkout processes. It includes robust token-based authorization to ensure secure access to sensitive data.

Features

GraphQL Queries

• Customer Search: Search for customers by email address
• Order Retrieval: Get order details by order number (including guest orders)
• Enhanced Customer Data: Additional customer fields with custom resolvers

GraphQL Mutations

• Order Assignment: Assign a previously guest order to an existing customer account
• Cart Unlock: Reactivate a locked cart and reset its associated order status
• Cart Deactivation: Disable an active cart to prevent further checkout actions

GraphQL Types

• Customer Extensions: Additional customer fields like tapbuy_customer_id
• Order Extensions: Enhanced order data including custom shipping assignments and state information
• Payment Method Extensions: Detailed payment information including additional data
• Address Extensions: Extended address information with entity IDs

Security

• Token-based Authorization: Secure API access using OAuth tokens
• Integration Permissions: Granular permission checking based on integration settings
• Resource-based Access Control: Different permission levels for different operations

Installation

1. Copy the module to your Magento installation:

2. Enable the module:

3. Run setup upgrade:

4. Compile DI:

5. Clear cache:

Configuration

Token Authorization Setup

1. Create Integration: Go to System → Extensions → Integrations in Magento Admin
2. Configure Permissions: Assign appropriate permissions:
   • Magento_Customer::customer - For customer operations
   • Magento_Sales::actions_view - For order operations
3. Generate Tokens: Activate the integration to generate access tokens

Required Permissions

The module requires the following ACL resources:

• Magento_Customer::customer - Customer data access
• Magento_Sales::actions_view - Order data access
• Magento_Backend::admin or Magento_Backend::all - Full admin access (alternative)

Usage

Authentication

All GraphQL queries require a Bearer token in the Authorization header:

GraphQL Queries

Search Customer by Email

Get Order by Number

Takes order_number or order_id

GraphQL Mutations

Assign Guest Order to Customer

order_id accepts either the order entity ID or its increment ID. Use order_identifier_type (auto, entity_id, or increment_id) to disambiguate when necessary. The order email must match the customer's email address before assignment.

Unlock Cart

Supply either a masked or numeric cart ID; unlock_reason is optional and impacts the resulting order status.

Deactivate Cart

Payment Method Integration

The module includes a plugin for SetPaymentMethodOnCart that handles additional Tapbuy payment information:

Architecture

Authorization Flow

1. Token Extraction: Extract Bearer token from Authorization header
2. Token Validation: Validate token against Magento's OAuth system
3. Integration Check: Verify integration status and permissions
4. Resource Authorization: Check specific ACL resource permissions
5. Data Access: Allow or deny access based on authorization results

File Structure

Error Handling

The module provides comprehensive error handling:

• Authorization Errors: Clear messages for token and permission issues
• Validation Errors: Input validation with descriptive error messages
• Not Found Errors: Appropriate responses for missing entities
• Logging: Error logging for debugging purposes

Security Considerations

• Token Validation: All requests validate OAuth tokens
• Permission Checking: Granular ACL resource checking
• Input Sanitization: Proper validation of all input parameters
• Error Disclosure: Minimal error information disclosure

Development

Adding New Resolvers

1. Create resolver class in Model/Resolver/
2. Implement ResolverInterface
3. Add authorization check using TokenAuthorization
4. Register in etc/di.xml
5. Define schema in etc/schema.graphqls

Extending Authorization

The TokenAuthorization class can be extended to support additional authorization mechanisms or custom permission logic.

Troubleshooting

Common Issues

1. "Token is required" Error

   • Ensure Authorization header is present
   • Verify Bearer token format

2. "Invalid token" Error

   • Check token validity in Magento Admin
   • Regenerate integration tokens if needed

3. "You do not have permission" Error

   • Verify integration permissions
   • Check ACL resource assignments
4. "Order not found" Error
   • Verify order number exists

Development

Running Tests

Tests run inside a Docker container that replicates the CI environment (PHP 8.3, Magento 2.4.7-p5). Docker must be running.

Prerequisites: clone the following sibling repository next to this one:

First-time setup:

Run all unit tests:

On the first run, the Docker image is built and Magento is installed into a named volume (tapbuy-magento-2.4.7-p5-php83). Subsequent runs reuse the cached volume and are fast.

Do not use composer test — it runs PHPUnit without the Magento bootstrap and will fail or produce misleading results.

Linting

Linting runs PHPMD and PHPCS (Magento2 standard) inside the same Docker container as tests. Docker must be running.

Run both linters:

Run individually:

Both linters always run when using make lint; if either fails, the command exits with a non-zero code.

• Check order visibility settings