Troubleshooting

Common issues and solutions when working with the Uganda Securities Exchange API library

Common issues

This guide covers common issues you might encounter when using the Uganda Securities Exchange API library and their solutions.

Unable to load HTML from URL

This error occurs when the library cannot fetch data from the Uganda Securities Exchange website or other external sources.

Possible causes:

• Network connectivity issues
• The target website is down or temporarily unavailable
• Server firewall blocking outbound requests
• SSL/TLS certificate issues

Solutions:

1. Verify your internet connection is working
2. Check if the USE website (https://www.use.or.ug) is accessible in your browser
3. Ensure your PHP installation has allow_url_fopen enabled in php.ini:
   allow_url_fopen = On
   
4. If using cURL, verify the ext-curl and ext-openssl extensions are installed:
   php -m | grep curl
   php -m | grep openssl
   

No table found on the page

Issue: The scraper cannot locate the expected table structure on the webpage.

Possible causes:

• The website structure has changed
• JavaScript-rendered content (not accessible to PHP DOM parser)
• Incorrect selector

Solutions:

1. Inspect the current website structure to verify the table still exists
2. Check if the content requires JavaScript to load (this library only works with static HTML)
3. Update your selectors if the website structure has changed
4. Consider implementing error handling:
   $table = $html->find('table', 0);
   if (!$table) {
       // Handle missing table gracefully
       error_log('Table not found on page');
       return [];
   }
   

Memory limit exceeded errors

Large HTML documents can consume significant memory during parsing.

Solutions:

1. Increase PHP memory limit in php.ini:
   memory_limit = 256M
   
2. Or set it at runtime in your script:
   ini_set('memory_limit', '256M');
   
3. Always clear DOM objects after use:
   $html->clear();
   unset($html);
   
4. Process data in smaller chunks when possible

Encoding and character set issues

Issue: Special characters or non-ASCII text appears garbled.

Solutions:

1. Ensure the ext-iconv extension is installed (required dependency):
   php -m | grep iconv
   
2. Install the optional ext-mbstring extension for better multi-byte character support:
   # Ubuntu/Debian
   sudo apt-get install php-mbstring
   
   # CentOS/RHEL
   sudo yum install php-mbstring
   
3. Verify your database and files are using UTF-8 encoding

Composer dependency installation fails

Issue: Unable to install the Simple HTML DOM Parser dependency.

Solutions:

1. Ensure Composer is installed and up to date:
   composer --version
   composer self-update
   
2. Check PHP version meets minimum requirement (PHP >= 5.6):
   php -v
   
3. Clear Composer cache and try again:
   composer clear-cache
   composer install
   
4. If behind a proxy, configure Composer proxy settings

Selectors not finding elements

Issue: CSS selectors return no results even though elements exist.

Common mistakes:

• Using incorrect selector syntax
• Assuming JavaScript-modified DOM structure
• Whitespace or formatting differences

Solutions:

1. Test selectors incrementally from parent to child
2. View the actual HTML source (not browser inspector which may show JS-modified DOM)
3. Use more flexible selectors:
   // Instead of specific classes that might change
   $element = $html->find('div.specific-class', 0);
   
   // Use more general selectors
   $element = $html->find('div[class*="partial-class"]', 0);
   
4. Add debugging to see what’s actually found:
   $elements = $html->find('your-selector');
   error_log('Found ' . count($elements) . ' elements');
   

PHP environment issues

The Uganda Securities Exchange API library requires specific PHP extensions and configurations.

Required extensions

Verify all required extensions are installed:

php -m | grep -E "iconv|curl|openssl|mbstring"

Required:

• ext-iconv - Character encoding conversion
• PHP >= 5.6

Recommended:

• ext-curl - HTTP requests (especially for HTTPS)
• ext-openssl - SSL/TLS support
• ext-mbstring - Multi-byte string handling

Server configuration

Ensure these php.ini settings are properly configured:

; Allow URL file operations
allow_url_fopen = On

; Increase limits for web scraping
max_execution_time = 60
memory_limit = 256M

; Error reporting during development
error_reporting = E_ALL
display_errors = On

Web scraping best practices

Following these practices helps prevent issues and ensures reliable operation.

Rate limiting

Implement delays between requests to avoid overwhelming the target server:

// Add delay between requests
sleep(1); // Wait 1 second

// Or use microseconds for shorter delays
usleep(500000); // Wait 0.5 seconds

Error handling

Always implement proper error handling:

try {
    $html = file_get_html($url);
    
    if (!$html) {
        throw new Exception('Failed to load HTML');
    }
    
    // Process HTML
    
    $html->clear();
    unset($html);
    
} catch (Exception $e) {
    error_log('Scraping error: ' . $e->getMessage());
    // Return graceful error response
    return json_encode(['error' => 'Unable to fetch data']);
}

User agent configuration

Some websites require a valid user agent:

$userAgent = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36';

$options = [
    'http' => [
        'header' => 'User-Agent: ' . $userAgent,
    ],
];

$context = stream_context_create($options);
$html = file_get_html($url, false, $context);

Legal and ethical considerations

Important: Production use requires approval from the Uganda Securities Commission.

Before deploying this library in a production environment:

1. Review the Uganda Securities Exchange website’s terms of service
2. Contact the Uganda Securities Commission for permission
3. Email them explaining your intended use case
4. Wait for explicit approval before proceeding

Visit the Uganda Securities Exchange website for contact information.

Getting help

If you continue experiencing issues:

1. Check the Simple HTML DOM Parser documentation
2. Review the source code examples in the repository
3. Enable PHP error logging to capture detailed error messages:
   error_reporting(E_ALL);
   ini_set('display_errors', 1);
   ini_set('log_errors', 1);
   ini_set('error_log', '/path/to/error.log');
   
4. Test your PHP environment configuration:
   php -i | grep -E "allow_url_fopen|memory_limit|max_execution_time"
   

When reporting issues, include your PHP version, installed extensions, and relevant error messages.