README

An unofficial PHP client to retrieve news data from the G1 website, a property of Globo Comunicação e Participações S.A..

This project is intended strictly for educational and study purposes. It has no commercial intent and does not claim ownership of any content retrieved from G1.

The goal is to provide a simple, structured, and developer-friendly way to access Brazilian news metadata programmatically.

Features

• Fetch latest news headlines from G1
• Filter news by Brazilian state (UF)
• Pagination support
• Structured responses via typed objects
• Optional filesystem cache with configurable TTL

Note This is not an official API and may break if G1 changes its internal structure.

Installation

Install via Composer:

composer require adaiasmagdiel/g1-client

Basic Usage

<?php

require_once __DIR__ . '/vendor/autoload.php';

use AdaiasMagdiel\G1\Client;
use AdaiasMagdiel\G1\Enum\Estado;

// Initialize the client (cache enabled by default)
$api = new Client();

// Fetch latest news from all regions
$resAll = $api->ultimas();
echo $resAll->news[0]->title . PHP_EOL;

// Fetch latest news from a specific state (e.g., Pará)
$resPara = $api->ultimas(estado: Estado::PARA);
echo $resPara->news[0]->title . PHP_EOL;

// Fetch page 2 of the latest news
$resPage2 = $api->ultimas(page: 2);
echo $resPage2->news[0]->title . PHP_EOL;

Cache Configuration

The client includes an optional filesystem cache.

Enable cache (default)

$api = new Client(
    cache: true,
    cacheDir: __DIR__ . '/.g1-cache',
    cacheTtl: 600 // seconds
);

Disable cache entirely

$api = new Client(cache: false);

When disabled:

• No filesystem access
• No cache reads or writes
• All requests hit the network directly

Cache Usage Recommendation

⚠️ Important Notice

Although the cache can be fully disabled, this is strongly discouraged in production or frequent usage scenarios.

Disabling the cache causes:

• A significantly higher number of HTTP requests to G1 servers
• Slower response times
• Increased risk of temporary blocks or rate limiting
• Unnecessary load on a third-party service

For this reason, it is highly recommended to keep the cache enabled whenever possible, especially when:

• Fetching multiple pages
• Iterating through states (Estado::cases())
• Building dashboards, feeds, or automated tools

The cache exists to:

• Reduce network traffic
• Improve performance
• Be respectful to the source website

Use the cache responsibly.

Working with News Items

The response returned by ultimas() is an instance of Ultimas, which contains a news array.

Each item in news is an instance of News with the following properties:

Example: Accessing an image

$img =
    $news->images['S']['url']
    ?? $news->images['M']['url']
    ?? $news->images['L']['url']
    ?? null;

Legal Notice

This project:

• Is not affiliated with Globo
• Does not redistribute copyrighted content
• Only consumes publicly available metadata
• Exists for learning, testing, and research purposes

Use responsibly.

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).

You are free to use, modify, and distribute this software under the terms of the GPLv3. Any derivative work must also be distributed under the same license.

See the LICENSE file for full details.