Accessibility

Accessibility Analysis

Overview

The accessibility analysis features provide tools to analyze web pages for accessibility issues, focusing on compliance with WCAG 2.1 standards at levels A and AA, which are required for Australian government websites and recommended for all Australian websites.

The implementation combines static analysis of HTML content with AI-powered analysis using OpenAI to provide comprehensive accessibility reports.

Features

Basic accessibility checks for common issues (missing alt text, form labels, heading hierarchy, etc.)
AI-powered analysis using OpenAI for more complex accessibility issues
Support for both synchronous and asynchronous (queued) analysis
Configuration options to customize the analysis behavior
Service class with a simple API for developers

Configuration

The following configuration options are available in the config/textstem.php file:

'accessibility' => [
    'enabled' => env('ACCESSIBILITY_ENABLED', true),
    'use_queue' => env('ACCESSIBILITY_USE_QUEUE', true),
    'wcag_level' => env('ACCESSIBILITY_WCAG_LEVEL', 'AA'), // 'A', 'AA', or 'AAA'
    'check_on_save' => env('ACCESSIBILITY_CHECK_ON_SAVE', false),
    'store_reports' => env('ACCESSIBILITY_STORE_REPORTS', true),
    'report_retention_days' => env('ACCESSIBILITY_REPORT_RETENTION_DAYS', 30),
],

enabled: Whether accessibility analysis is enabled
use_queue: Whether to use a queue for accessibility analysis (recommended for production)
wcag_level: The WCAG level to check against (A, AA, or AAA)
check_on_save: Whether to automatically check accessibility when saving content
store_reports: Whether to store accessibility reports
report_retention_days: How long to retain accessibility reports (in days)

Usage

Using the Facade

The easiest way to use the accessibility analysis features is through the Accessibility facade:

use Medialight\Textstem\Facades\Accessibility;

// Analyze a URL
$report = Accessibility::analyzeUrl('https://example.com');

// Analyze HTML content
$html = '<html>...</html>';
$report = Accessibility::analyzeHtml('https://example.com', $html);

// Analyze with a callback (useful for queued analysis)
Accessibility::analyzeUrl('https://example.com', function ($report) {
    // Do something with the report
    Log::info('Accessibility report generated', $report);
});

// Get configuration values
$wcagLevel = Accessibility::getWcagLevel(); // 'A', 'AA', or 'AAA'
$checkOnSave = Accessibility::shouldCheckOnSave();
$storeReports = Accessibility::shouldStoreReports();
$retentionDays = Accessibility::getReportRetentionDays();

Using the Service Class

You can also use the AccessibilityService class directly via dependency injection:

use Medialight\Textstem\Services\AccessibilityService;

class MyController
{
    protected $accessibilityService;

    public function __construct(AccessibilityService $accessibilityService)
    {
        $this->accessibilityService = $accessibilityService;
    }

    public function checkUrl(Request $request)
    {
        $url = $request->input('url');
        $report = $this->accessibilityService->analyzeUrl($url);

        return view('accessibility-report', ['report' => $report]);
    }
}

Or you can resolve it from the container:

$service = app(AccessibilityService::class);
$report = $service->analyzeUrl('https://example.com');

Report Structure

The accessibility report has the following structure:

[
    'url' => 'https://example.com',
    'timestamp' => '2023-06-01T12:34:56+00:00',
    'basic_issues' => [
        [
            'type' => 'error',
            'code' => 'img-no-alt',
            'message' => 'Image missing alt text',
            'element' => [
                'tag' => 'img',
                'attributes' => ['src' => 'image.jpg'],
                'snippet' => '<img src="image.jpg">',
            ],
            'wcag' => '1.1.1',
            'level' => 'A',
        ],
        // More issues...
    ],
    'ai_analysis' => [
        'summary' => 'The page has several accessibility issues...',
        'critical_issues' => [
            'WCAG 1.1.1 (Non-text Content): Images missing alt text...',
            // More critical issues...
        ],
        'important_issues' => [
            'WCAG 1.4.3 (Contrast): Text has insufficient contrast...',
            // More important issues...
        ],
        'recommendations' => [
            'Add alt text to all images...',
            // More recommendations...
        ],
        'compliance_status' => 'The page does not comply with WCAG 2.1 Level AA...',
    ],
]

Using the Helper Class Directly

For more advanced use cases, you can use the AccessibilityHelper class directly:

use Medialight\Textstem\Helpers\AccessibilityHelper;

// Perform basic accessibility checks
$issues = AccessibilityHelper::basicAccessibilityChecks($html);

// Prepare HTML for OpenAI analysis
$preparedHtml = AccessibilityHelper::prepareHtmlForAnalysis($html);

// Generate a prompt for OpenAI
$prompt = AccessibilityHelper::generateAccessibilityPrompt($preparedHtml);

// Parse the OpenAI response
$analysis = AccessibilityHelper::parseAccessibilityResponse($response);

Using the Job Class

For background processing, you can dispatch the AccessibilityAnalysisJob directly:

use Medialight\Textstem\Jobs\AccessibilityAnalysisJob;

// Dispatch the job
AccessibilityAnalysisJob::dispatch('https://example.com', $html, function ($report) {
    // Do something with the report
    Log::info('Accessibility report generated', $report);
});

Australian Web Accessibility Standards

Australian web accessibility standards are based on the Web Content Accessibility Guidelines (WCAG) 2.1. The Australian Government requires all government websites to comply with WCAG 2.1 at Level AA, and recommends the same for all Australian websites.

Key requirements include:

Perceivable: Information and user interface components must be presentable to users in ways they can perceive.
Operable: User interface components and navigation must be operable.
Understandable: Information and the operation of the user interface must be understandable.
Robust: Content must be robust enough that it can be interpreted by a wide variety of user agents, including assistive technologies.

For more information, see:

Benefits

Implementing accessibility analysis in your website provides several benefits:

Compliance: Ensures compliance with Australian web accessibility standards and regulations.
Inclusivity: Makes your website accessible to a wider audience, including people with disabilities.
SEO: Many accessibility improvements also benefit search engine optimization.
User Experience: Accessibility improvements often lead to better user experience for all users.
Legal Protection: Reduces the risk of legal issues related to accessibility discrimination.