Getting Started

Minimal Setup

Installation
```
composer require a5sys/mantis-api-bundle
```
Ensure php_soap is enabled in your PHP environment.

Enable the Bundle Add to config/bundles.php (Laravel 5.4+):

return [
    // ...
    A5sys\MantisApiBundle\MantisApiBundle::class,
];

Configure Add to .env:

MANTIS_LOGIN=your_username
MANTIS_PASSWORD=your_password
MANTIS_URL=https://your-mantis-instance

Then define in config/services.php (or config/packages/mantis_api.yaml in Symfony):

mantis_api:
    login: "%env(MANTIS_LOGIN)%"
    password: "%env(MANTIS_PASSWORD)%"
    url: "%env(MANTIS_URL)%/api/soap/mantisconnect.php"
    verify_peer: true
    verify_peer_name: true
    allow_self_signed: false

First Use Case Inject the MantisApi service and call a method (e.g., fetch issues):

use A5sys\MantisApiBundle\Service\MantisApi;

public function fetchIssues(MantisApi $mantisApi) {
    $issues = $mantisApi->mc_issue_get($filter = '', $limit = 10);
    return $issues;
}

Implementation Patterns

Core Workflows

Issue Management

Create: Use mc_issue_add() with an array of issue fields.

$newIssue = [
    'summary' => 'Bug: Login fails',
    'description' => 'Users cannot log in...',
    'category' => 1,
];
$mantisApi->mc_issue_add($newIssue);

Update: Use mc_issue_update() with the issue ID.

$mantisApi->mc_issue_update($issueId, ['status' => 80]); // 80 = Resolved

Fetch: Use mc_issue_get() with filters (e.g., status=80 for resolved issues).

User Management

Fetch Users: Use mc_user_get() with optional filters.

$users = $mantisApi->mc_user_get('username LIKE "j%"');

Create User: Use mc_user_add() with user details.

$newUser = [
    'username' => 'jdoe',
    'email' => 'jdoe@example.com',
    'realname' => 'John Doe',
    'password' => 'securepassword123',
];
$mantisApi->mc_user_add($newUser);

Project Management

Fetch Projects: Use mc_project_get().

$projects = $mantisApi->mc_project_get();

Create Project: Use mc_project_add().

$newProject = [
    'name' => 'New Feature',
    'description' => 'Add X feature',
];
$mantisApi->mc_project_add($newProject);

Event-Driven Patterns

Webhook Integration: Poll for changes using mc_issue_get() in a scheduled job (e.g., Laravel's schedule:run).

$this->app->booted(function () {
    $schedule->call(function () {
        $newIssues = $mantisApi->mc_issue_get('last_updated > NOW() - INTERVAL 1 HOUR');
        // Process newIssues...
    })->hourly();
});

Bulk Operations

Use loops with mc_issue_get() for batch processing (e.g., updating statuses).

$issues = $mantisApi->mc_issue_get('status=10'); // 10 = New
foreach ($issues as $issue) {
    $mantisApi->mc_issue_update($issue['id'], ['status' => 80]); // Resolve
}

Gotchas and Tips

Pitfalls

SOAP SSL Issues
- If verify_peer or verify_peer_name is true but your Mantis instance uses a self-signed certificate, requests will fail.
  - Fix: Set allow_self_signed: true in config (not recommended for production).
  - Better Fix: Use a valid SSL certificate for your Mantis instance.
Authentication Failures
- Hardcoded credentials in config.yml are insecure. Always use environment variables (.env) and parameter bags.
- Debug Tip: Check Mantis logs (mantisbt.log) for authentication errors.

Rate Limiting

The SOAP API may throttle requests. Implement exponential backoff in your client:

try {
    $mantisApi->mc_issue_get();
} catch (\SoapFault $e) {
    if ($e->faultcode === 'SOAP-ENV:Server') {
        sleep(2); // Retry after delay
        retry();
    }
    throw $e;
}

Field Validation
- Mantis API is strict about required fields (e.g., summary is mandatory for mc_issue_add).
  - Tip: Use mc_issue_get_fields() to validate required fields before submission.
Deprecated Methods
- The bundle is outdated (last release: 2019). Some Mantis API methods may have changed.
  - Workaround: Check the MantisBT SOAP API docs for updates and adjust calls accordingly.

Error Handling

SOAP faults are thrown as SoapFault exceptions. Catch and log them:

try {
    $mantisApi->mc_issue_add($issue);
} catch (SoapFault $e) {
    Log::error('Mantis API Error: ' . $e->getMessage());
    throw new \RuntimeException('Failed to create issue in Mantis', 0, $e);
}

Debugging Tips

Enable SOAP Debugging Add to config/services.php:
```
mantis_api:
    # ... existing config ...
    debug: true
```
This may expose raw SOAP responses in logs.

Log Raw Requests/Responses Extend the MantisApi service to log SOAP envelopes:

$mantisApi->setLogger(function ($message) {
    Log::debug('Mantis API: ' . $message);
});

Test Locally Use a local MantisBT instance (e.g., Docker) for development:
```
docker run -p 8080:80 mantisbt/mantisbt
```

Extension Points

Custom SOAP Headers Override the MantisApi service to add headers (e.g., for authentication):
```
$client = $mantisApi->getClient();
$client->__setSoapHeaders([new SoapHeader(...)]);
```

Add Middleware Wrap the SOAP client to add logging, retries, or caching:

$client = new \SoapClient($wsdl, [
    'trace' => 1,
    'exceptions' => true,
    'stream_context' => stream_context_create([
        'ssl' => [
            'verify_peer' => true,
            'cafile' => '/path/to/cert.pem',
        ]
    ]),
]);

Event Listeners Dispatch Laravel events after API calls (e.g., IssueCreated):
```
$mantisApi->mc_issue_add($issue);
event(new IssueCreated($issue));
```

Repository Pattern Create a facade or repository to abstract API calls:

class MantisIssueRepository {
    public function __construct(private MantisApi $mantisApi) {}

    public function findByStatus(int $status): array {
        return $this->mantisApi->mc_issue_get("status=$status");
    }
}

Testing Mock the MantisApi service in PHPUnit:

$this->mock(MantisApi::class)->shouldReceive('mc_issue_get')
    ->once()
    ->andReturn([['id' => 1, 'summary' => 'Test Issue']]);

Mantis Api Bundle Laravel Package