NetCurl

NetCurl är ett PHP-bibliotek för kommunikation byggt runt en central idé: applikationskoden ska normalt beskriva vad som ska hämtas eller skickas, inte vilken låg-nivå-transport som måste utföra anropet.

Den underhållna 6.1-linjen kan välja mellan flera inbyggda drivers vid runtime. Det viktiga kompatibilitetskontraktet är att klientkod inte ska behöva olika affärslogik för cURL, PHP streams, SOAP, RSS/XML eller registrerade egna drivers när samma logiska request kan hanteras av flera transporter.

Källkod och ärendehantering:

Installation

composer require tornevall/tornelib-php-netcurl:^6.1

Dra inte slutsatser om PHP-stöd enbart från gamla README-texter eller äldre byggsystem. Den aktuellt underhållna kompatibilitetsbilden finns i repositoryts GitHub Actions-matris.

Det gamla påståendet om PHP 5.6-stöd gäller inte längre för dagens 6.1-källkod.

Det viktiga: automatiskt val av driver

För ett vanligt anrop använder du NetWrapper och låter NetCurl välja en fungerande transport:

use TorneLIB\Module\Network\NetWrapper;

$client = new NetWrapper();
$client->request('https://example.com/api/status');

$body = $client->getBody();
$status = $client->getCode();
$driver = $client->getCurrentWrapperClass(true);

Applikationen behöver inte själv instansiera CurlWrapper eller SimpleStreamWrapper.

För de inbyggda drivrarna routar 6.1 i huvudsak så här:

SOAP för WSDL-liknande requests när SoapClient finns.
RSS-hantering när DataType::RSS_XML efterfrågas.
cURL för vanliga HTTP-requests när cURL finns.
PHP streams när cURL saknas men stream-motorn kan utföra requesten.
Registrerade externa drivers enligt vald prioritet.

Fallback-beteendet är en del av NetCurls kärndesign, inte en tillfällig implementation.

cURL är förstahandsval, inte ett absolut krav

En typisk installation kan innehålla cURL, XML och SOAP:

apt-get install php-curl php-xml php-soap

Men vanlig HTTP-kommunikation ska inte kräva cURL bara för att NetCurl ska kunna initieras. Om cURL saknas och PHP streams fungerar ska NetCurl kunna välja stream-drivern i stället.

För HTTP/HTTPS-fallback via streams i 6.1 måste PHP:s URL-aware stream wrappers vara användbara. I praktiken måste allow_url_fopen vara aktiverat för att SimpleStreamWrapper ska kunna hantera externa URL:er.

Detta testas nu uttryckligen eftersom vi hittade en regression där cURL-konstanter lästes innan fallbacken ens hann väljas:

#23 - Fix NetWrapper initialization when cURL is unavailable

Usecase: använd medvetet en specifik wrapper

NetWrapper är normalt rätt val för applikationskod eftersom automatisk routing och fallback behålls. Direkt wrapper-användning är ändå användbar när applikationen medvetet garanterar en viss transport och behöver transport-specifikt beteende.

En miljö där cURL är garanterat kan exempelvis använda CurlWrapper direkt:

use TorneLIB\Module\Network\Wrappers\CurlWrapper;

$client = new CurlWrapper();
$client->request('https://example.com/api/status');

$body = $client->getBody();

Då avstår man medvetet från NetWrapper-fallbacken. Använd detta främst när det är ett uttryckligt designval eller vid tester/diagnostik av en enskild transport.

Usecase: POST med JSON och sedan rå eller parsad output

Inputformat och outputåtkomst är separata delar.

use TorneLIB\Model\Type\DataType;
use TorneLIB\Model\Type\RequestMethod;
use TorneLIB\Module\Network\NetWrapper;

$client = new NetWrapper();
$client->request(
    'https://example.com/api/items',
    [
        'name' => 'Example',
        'enabled' => true,
    ],
    RequestMethod::POST,
    DataType::JSON
);

$raw = $client->getBody();
$parsed = $client->getParsed();
$status = $client->getCode();

Requestdatan kodas som JSON för transporten, medan samma färdiga response fortfarande kan läsas både som rå body och genom NetCurls parsade representation.

Usecase: skicka XML utan att byta klientmodell

use TorneLIB\Model\Type\DataType;
use TorneLIB\Model\Type\RequestMethod;
use TorneLIB\Module\Network\NetWrapper;

$client = new NetWrapper();
$client->request(
    'https://example.com/api/xml',
    '<request><id>123</id></request>',
    RequestMethod::POST,
    DataType::XML
);

$response = $client->getParsed();

Arrayer kan också konverteras till XML av konfigurationslagret när XML är valt som requestformat.

Usecase: vanlig form/query-data

Använd DataType::NORMAL för vanlig HTTP form/query-hantering:

use TorneLIB\Model\Type\DataType;
use TorneLIB\Model\Type\RequestMethod;
use TorneLIB\Module\Network\NetWrapper;

$client = new NetWrapper();
$client->request(
    'https://example.com/api/search',
    ['query' => 'netcurl'],
    RequestMethod::GET,
    DataType::NORMAL
);

Samma requestmetod används oavsett om den valda transporten blir cURL eller en stream-implementation.

Usecase: SOAP/WSDL utan hårdkodad SoapClient

En URL som innehåller ?wsdl eller &wsdl behandlas av NetWrapper som en SOAP/WSDL-liknande request.

När PHP:s SoapClient finns väljer NetCurl SOAP-wrappern. När SOAP saknas kan nuvarande 6.1-router falla tillbaka på XML över HTTP där requesten säkert kan representeras på det sättet.

use TorneLIB\Module\Network\NetWrapper;

$client = new NetWrapper();
$client->request('https://example.com/service?wsdl');

$driver = $client->getCurrentWrapperClass(true);

Instansiera inte SoapClientWrapper i vanlig applikationskod bara för att välja transport. Direkt wrapper-användning är till för fall där transport-specifikt beteende uttryckligen behövs.

Usecase: RSS/XML

RSS kan väljas genom DataType::RSS_XML:

use TorneLIB\Model\Type\DataType;
use TorneLIB\Model\Type\RequestMethod;
use TorneLIB\Module\Network\NetWrapper;

$client = new NetWrapper();
$client->request(
    'https://example.com/feed.xml',
    [],
    RequestMethod::GET,
    DataType::RSS_XML
);

$feed = $client->getParsed();

Valfria feed-bibliotek kan ge rikare RSS-hantering, men NetCurl behåller en egen fallback så att en optional dependency inte automatiskt blir ett hårt krav.

Usecase: headers, autentisering, proxy och timeout

Gemensam konfiguration sätts innan vald transport utför requesten:

use TorneLIB\Model\Type\AuthType;
use TorneLIB\Module\Network\NetWrapper;

$client = new NetWrapper();

$client
    ->setHeader('X-Client', 'my-service')
    ->setAuthentication('username', 'password', AuthType::BASIC)
    ->setTimeout(15)
    ->setProxy('proxy.example.net:8080');

$client->request('https://example.com/private-api');

Poängen med det gemensamma konfigurationslagret är att anroparen inte ska behöva en autentiserings/header/timeout-konfiguration för cURL och en annan för streams eller SOAP när den valda drivern stöder samma logiska option.

State per instans

Konfigurationen hör till NetWrapper-instansen. Separata klienter kan därför ha olika headers, autentisering, proxy och timeout:

$first = new NetWrapper();
$first->setHeader('X-Tenant', 'first');

$second = new NetWrapper();
$second->setHeader('X-Tenant', 'second');

Det beteendet låses nu med deterministiska kontrakttester innan 6.2-refaktoreringen.

Usecase: flera requests

NetWrapper::request() accepterar även en associativ request-map. Varje entry kan bära egen data, metod, datatype och valfri WrapperConfig:

use TorneLIB\Model\Type\DataType;
use TorneLIB\Model\Type\RequestMethod;
use TorneLIB\Module\Network\NetWrapper;

$client = new NetWrapper();

$client->request([
    'https://example.com/one' => [
        [],
        RequestMethod::GET,
        DataType::NORMAL,
    ],
    'https://example.com/two' => [
        ['name' => 'Example'],
        RequestMethod::POST,
        DataType::JSON,
    ],
]);

$firstBody = $client->getBody('https://example.com/one');
$secondParsed = $client->getParsed('https://example.com/two');

Multi-request-beteendet ingår i kompatibilitetskontraktet och får deterministiska tester i stället för att endast förlita sig på externa integrationstest-endpoints.

Usecase: egna/externa drivers

Applikationer kan registrera ett objekt som implementerar NetCurls WrapperInterface:

$client = new NetWrapper();
$client->register($myDriver, true);
$client->request('custom-or-http-target');

Det andra argumentet styr om registrerade drivers ska provas före de inbyggda. Med false förblir de inbyggda förstahandsval och externa drivers fungerar som senare fallback.

Detta är en viktig extension point och ska finnas kvar i 6.2 och 7.0.

Se vilken driver som användes

Vanlig klientkod ska normalt inte bry sig, men vid diagnostik kan vald wrapper inspekteras:

$client->request('https://example.com/');

printf(
    "Driver: %s\n",
    $client->getCurrentWrapperClass(true)
);

Det är användbart i tester och diagnostik utan att göra transportvalet till en del av affärslogiken.

Legacy `MODULE_CURL`

MODULE_CURL finns i 6.1 endast som kompatibilitetsfacade för äldre 6.0-klienter.

Gammal kod kan fortfarande se ut så här:

use TorneLIB\MODULE_CURL;

$legacy = new MODULE_CURL();
$response = $legacy->doGet('https://example.com/');

För ny 6.1-kod bör NetWrapper användas:

use TorneLIB\Module\Network\NetWrapper;

$client = new NetWrapper();
$response = $client->request('https://example.com/');

MODULE_CURL är deprecated i 6.1 och planeras bort i 6.2. Migrationen designas avsiktligt så att äldre anropsmönster kan flyttas framåt utan att förlora NetCurls flexibla argument- och transportbeteende.

Riktning för 6.1, 6.2 och 7.0

6.1

6.1 är kompatibilitets- och referenslinjen. Befintligt beteende dokumenteras med betydligt fler deterministiska tester och fel som hittas av testerna rättas utan stora arkitekturförändringar.

6.2

6.2 är bryggan för cleanup/ombyggnad. MODULE_CURL planeras bort, men automatisk driver-routing, flexibla requestformat, egna drivers, rå/parsad response och legacy-vänliga anropsmönster får inte försvinna med den.

7.0

7.0 planeras för PHP 8.3 och nyare med typade/model-orienterade internals. Den moderna kärnan ska fortfarande behålla NetCurls ursprungliga styrka: klienter kan använda en enkel high-level facade medan transporter är utbytbara och väljs automatiskt.

Kraven mellan versionerna följs i:

Tester och kompatibilitet

Den underhållna teststrategin delas i två typer av coverage:

deterministiska lokala tester för config, parsning, input/output och driver-kontrakt
miljö/capability-tester där PHP-extensioner som cURL eller SOAP uttryckligen tas bort så att fallback faktiskt testas

Relevant tracking:

För aktuellt PHP-stöd ska repositoryts GitHub Actions-resultat användas i stället för historiska Bamboo-, Bitbucket-, Confluence- eller gamla README-påståenden.

Tornevall Networks

NetCurl

NetCurl

Installation

Det viktiga: automatiskt val av driver

cURL är förstahandsval, inte ett absolut krav

Usecase: använd medvetet en specifik wrapper

Usecase: POST med JSON och sedan rå eller parsad output

Usecase: skicka XML utan att byta klientmodell

Usecase: vanlig form/query-data

Usecase: SOAP/WSDL utan hårdkodad SoapClient

Usecase: RSS/XML

Usecase: headers, autentisering, proxy och timeout

State per instans

Usecase: flera requests

Usecase: egna/externa drivers

Se vilken driver som användes

Legacy MODULE_CURL

Riktning för 6.1, 6.2 och 7.0

6.1

6.2

7.0

Tester och kompatibilitet

Legacy `MODULE_CURL`