Favicon Fetcher

Starting with v2.0.0, the cache format changed from storing a simple string (the favicon URL) to storing an array that includes the favicon's size and type.

Important Considerations:

• Legacy Data: The package provides minor backwards-compatible support for items cached before v2.0.0. However, for these legacy items, the Favicon class's type and size properties will not be set.
• Future Deprecation: Backwards compatibility for the old string-based cache format is expected to be removed in v3.0.0. Only array-based cache entries will be supported then.

To implement custom fetching logic, create a class that implements the AshAllenDesign\FaviconFetcher\Contracts\Fetcher interface and register it using the extend method.

use AshAllenDesign\FaviconFetcher\Contracts\Fetcher;
use AshAllenDesign\FaviconFetcher\Favicon;
use AshAllenDesign\FaviconFetcher\Facades\Favicon;

class MyCustomDriver implements Fetcher
{
    public function fetch(string $url): ?Favicon
    {
        // Custom logic
    }

    public function fetchOr(string $url, mixed $default): mixed
    {
        // Custom logic
    }
}

// Register the driver
Favicon::extend('my-custom-driver', new MyCustomDriver());

// Use the driver
$favicon = Favicon::driver('my-custom-driver')->fetch('https://example.com');

To install the package, run the following Composer command in your Laravel project terminal:

composer require ashallendesign/favicon-fetcher

The package requires the following minimum versions to function correctly:

• PHP: 8.0+
• Laravel: 8.0+

After installing the package, publish its configuration file to your application's config directory using the Artisan command:

php artisan vendor:publish --provider="AshAllenDesign\FaviconFetcher\FaviconFetcherProvider"

Global HTTP settings can be configured in config/favicon-fetcher.php or via .env:

• connect_timeout: Time to wait for a connection (seconds).
• timeout: Time to wait for a response (seconds).
• verify_tls: Boolean to enable/disable TLS verification. Set to false for self-signed certs.
• user_agent: Custom User-Agent string for all requests.

Environment Variables:

• FAVICON_FETCHER_VERIFY_TLS (boolean)
• FAVICON_FETCHER_USER_AGENT (string)

To customize the package behavior, you can publish the configuration file to your application's config directory. This allows you to modify settings like drivers and timeouts without changing the package source.

Run the following Artisan command to publish the config:

php artisan vendor:publish --tag=favicon-fetcher-config

The FaviconFetcherProvider is a Laravel Service Provider that integrates the package into your application. It merges the default configuration and binds the favicon-fetcher service to the application container using the FetcherManager class.

To use the package, ensure this provider is registered in your Laravel application's config/app.php (for older Laravel versions) or is automatically discovered if using Laravel's package auto-discovery.

// The package binds the manager to the 'favicon-fetcher' key in the container
$fetcher = app('favicon-fetcher');

When upgrading to v3.0.0, note that the exception thrown during failed requests has changed. Instead of Illuminate\Http\Client\ConnectionException, the package now throws AshAllenDesign\FaviconFetcher\Exceptions\ConnectionException.

This exception is thrown when:

• The URL has a valid structure but the site does not exist.
• The HTTP client exceeds the connection timeout.
• The HTTP client exceeds the request timeout.

Use the fetchOr method to provide a default value if a favicon cannot be found. The second argument can be a string (the default URL) or a Closure. If a Closure is used, it receives the $url being queried as its first argument.

use AshAllenDesign\FaviconFetcher\Facades\Favicon;

// Using a string fallback
$favicon = Favicon::fetchOr('https://ashallendesign.co.uk', 'https://example.com/favicon.ico');

// Using a Closure fallback
$favicon = Favicon::fetchOr('https://ashallendesign.co.uk', function ($url) {
    return 'https://example.com/favicon.ico';
});