README

PHP library for the EasyNews search and NZB download service.

This library provides a PSR-4, PHP 8.0+ wrapper around the EasyNews members API for searching Usenet video releases and downloading NZB and video files.

Source repository: https://github.com/btafoya/easynewsdownloader

Requirements

PHP >= 8.0
ext-curl
ext-intl

Installation

composer require easynewsdownloader/easynews

Configuration

The library reads configuration from environment variables by default. You may also pass an explicit config array to the constructor.

Environment variables

Variable	Description	Default
`EASYNEWS_ENABLED`	Enable or disable the integration	`false`
`EASYNEWS_USERNAME`	EasyNews account username	—
`EASYNEWS_PASSWORD`	EasyNews account password	—
`EASYNEWS_MIN_SIZE_MB`	Minimum release size in MB	`100`
`EASYNEWS_TEXT_MODE_ONLY`	Disable strict metadata matching	`false`
`ADDON_BASE_URL`	Base URL used for generated download links	—

You can also pass a shared array of values as the first argument to the constructor:

$service = new EasyNewsDownloader\EasyNews\EasynewsService([
    'EASYNEWS_ENABLED'    => 'true',
    'EASYNEWS_USERNAME'   => 'myuser',
    'EASYNEWS_PASSWORD'   => 'mypass',
    'EASYNEWS_MIN_SIZE_MB'=> '200',
], [
    'sharedSecret' => 'my-secret',
]);

The second constructor argument is an optional runtime config array:

Key	Description
`addonBaseUrl`	Override `ADDON_BASE_URL`
`sharedSecret`	Secret segment added to generated download URLs

Quick start

require 'vendor/autoload.php';

use EasyNewsDownloader\EasyNews\EasynewsService;

$service = new EasynewsService();

$results = $service->searchEasynews([
    'rawQuery' => 'Dune 2024',
]);

foreach ($results as $result) {
    echo $result['title'] . ' - ' . $result['directUrl'] . PHP_EOL;
}

Searching

EasynewsService::searchEasynews() accepts an options array and returns a list of normalized results.

Options

Option	Type	Description
`rawQuery`	string	Primary search query
`fallbackQuery`	string	Query to use if `rawQuery` is empty
`year`	int	Expected release year
`season`	int	Expected season number
`episode`	int	Expected episode number
`strictMode`	bool	Enable strict metadata matching
`specialTextOnly`	bool	Treat the request as a text-only special request

Returned result fields

Each result is an associative array:

Field	Type	Description
`title`	string	Release title
`downloadUrl`	string	URL that can be used to download the NZB
`guid`	string	Unique identifier
`indexer`	string	Always `Easynews`
`indexerId`	string	Always `easynews`
`size`	int	Size in bytes
`pubDate`	string\|null	ISO 8601 post date
`publishDateMs`	int	Post date as milliseconds since epoch
`ageDays`	int	Age in days
`release`	array	Contains `resolution` and `languages`
`poster`	string\|null	Usenet poster
`easynewsPayload`	string	Base64-encoded payload used for NZB download
`directUrl`	string	Direct EasyNews video download URL
`_sourceType`	string	Always `easynews`
`group`	string\|null	Usenet group

Building search queries

For applications that start with metadata rather than a raw query string, use EasynewsQueryBuilder::buildEasynewsSearchParams(). It converts structured metadata into a set of search strings.

use EasyNewsDownloader\EasyNews\EasynewsQueryBuilder;

$params = EasynewsQueryBuilder::buildEasynewsSearchParams([
    'type'                => 'series',
    'tmdbTitles'          => [
        ['title' => 'Severance', 'asciiTitle' => 'Severance', 'language' => 'en'],
    ],
    'releaseYear'         => 2022,
    'seasonNum'           => 1,
    'episodeNum'          => 1,
    'textQueryFallbackValue' => 'Severance',
    'strictMode'          => true,
]);

// $params['queries']  => ['Severance S01E01']

Query builder input

Parameter	Type	Description
`type`	string	`movie` or `series`
`releaseYear`	int\|null	Release year
`seasonNum`	int\|null	Season number
`episodeNum`	int\|null	Episode number
`tmdbTitles`	array	Array of title objects with `title`, `asciiTitle`, and `language`
`isAnimeRequest`	bool	Whether to include anime titles
`animeSearchableTitles`	array	Anime title objects
`textQueryFallbackValue`	string\|null	Fallback raw query
`movieTitle`	string\|null	Movie title
`baseIdentifier`	string\|null	Last-resort identifier
`isSpecialRequest`	bool	Special/text-only mode
`specialMetadataTitle`	string\|null	Title to use in special mode
`requestLacksIdentifiers`	bool	Force text-only behavior
`strictMode`	bool	Enable strict matching
`normalizeToAscii`	callable\|null	Optional callable for ASCII normalization

Query builder output

Returns null when no usable queries can be built, otherwise an array with:

Key	Description
`queries`	Array of search strings
`fallbackQuery`	Query to use as a fallback
`year`	Parsed year
`season`	Parsed season
`episode`	Parsed episode
`strictMode`	Strict mode flag
`specialTextOnly`	Text-only flag

Downloading NZBs

Use a result's easynewsPayload with downloadEasynewsNzb():

$result = $results[0] ?? null;
if ($result !== null) {
    $nzb = $service->downloadEasynewsNzb($result['easynewsPayload']);

    file_put_contents($nzb['fileName'], $nzb['buffer']);
}

The returned array contains:

Field	Description
`buffer`	The NZB contents
`fileName`	Suggested file name
`contentType`	Content type header

Downloading video files

Each search result includes a directUrl that points to the raw video file on EasyNews. Use downloadVideoFile() to stream it straight to disk. The method resumes partial files, creates missing parent directories, and throws RuntimeException on failure.

$result = $results[0] ?? null;
if ($result !== null) {
    $service->downloadVideoFile($result, '/downloads/movie.mp4');
}

Behavior:

Streams directly to disk; large files are not loaded into memory.
Sends an HTTP Range request when the destination already exists so partial downloads resume.
Auto-creates the destination directory tree.
Returns true on success, throws RuntimeException on errors.

Helper scripts

The scripts/ directory contains convenience scripts for manual testing:

scripts/easynews_search.sh — Run an EasyNews search and print JSON results. Reads credentials from .env.
```
./scripts/easynews_search.sh 'Dune+2024+2160p'
```
scripts/search_and_download.php — Search for a specific release and download the first result to /tmp/. Reads credentials from .env.
```
./scripts/search_and_download.php
```

Credential check

echo $service->testEasynewsCredentials([
    'username' => 'myuser',
    'password' => 'mypass',
]);

Utilities

EasynewsUtils exposes the stateless helpers used by the service and query builder.

use EasyNewsDownloader\EasyNews\EasynewsUtils;

$ascii  = EasynewsUtils::foldAccents('Über');     // Ueber
$clean  = EasynewsUtils::cleanSearchTitle('Café'); // Cafe
$bool   = EasynewsUtils::toBoolean('yes', false);   // true
$date   = EasynewsUtils::coerceDate('2024-01-01');
$seconds = EasynewsUtils::parseDurationSeconds('1h30m'); // 5400

Notes

The service only returns results when EASYNEWS_ENABLED is truthy and both username and password are set.
Strict mode performs title, year, season, and episode validation against parsed release metadata.
The downloadUrl field assumes a downstream endpoint that accepts easynewsPayload and calls downloadEasynewsNzb().
The directUrl field is the raw EasyNews video URL and can be used directly with downloadVideoFile().

License

This project is released under the MIT License.

easynewsdownloader / easynews

Maintainers

Package info

Statistics

Security