PHP eksempler



PHP eksemplerne i dette afsnit bruger PHP SOAP modulet, som kan findes på http://php.net/manual/en/book.soap.php.

Vælg PHP eksempel nedenfor.

 

Opret en SOAP Klient

For at oprette forbindelse til en løsning oprettes der først et nyt SoapClient objekt. Som argument gives stien til WSDL-filen (Web Service Description Lanugage) for Hostedshop API. 

        $Client = new SoapClient('https://api.hostedshop.io/service.wsdl');
    

Filen kan findes på  https://api.hostedshop.io/service.wsdl, men kan med fordel ligges lokalt ved klienten da det giver udviklingsværktøjer såsom Zend mulighed for at give foreslag til, og mulighed for, at autocomplete funktioner der kan kaldes på klienten.

Bemærk at alle eksempler i denne sektion er via PHP soap client. Ved brug af denne til at forbinde til API'et kræves det at alle argumenter wrappes i et array, hvilket også kan ses eksemplerne i denne sektion.

Dokumentationen på https://api.hostedshop.io/doc/ angiver argumenter anderledes (der kan være mere end et argument).

Konventionen for brug af funktioner i PHP soap client er generelt at omdanne argumenter fra dokumentationen til et array med argument-navne som nøgler, og argument værdi som værdi. Eksempelvis:

Category_UpdateTitle (int $CategoryId, string $Title, string $LanguageISO)

i dokumentationen. Her vil kaldet via PHP soap client være:

Category_UpdateTitle (['CategoryId' => int, 'Title' => string, 'LanguageISO' => string])

 

Opret forbindelse til en løsning

Der kan nu skabes forbindelse til en specifik løsning: 

$Client->Solution_Connect (array('Username' => 'some_username', 'Password' =>'some_password'));

 

Vælg sprog

Hostedshop Webshop og CMS understøtter flere sprog. Et udtræk fra API’et er altid i ét specifikt sprog.
Dette sættes ved at angive den ønskede sprog ISO-kode for udtrækket. Følgende eksempel sætter sproget til dansk:

$Client->Solution_SetLanguage(array('LanguageISO' => 'DK'));

Dette påvirker både udtræk, opdateringer og oprettelse af nye entiteter. Listen over tilgængelige sprog og deres ISO kode for en løsning kan ses i administrationen under Indstillinger -> Sprog & domæner.

Sættes en ISO som ikke er i brug returneres en fejlkode. Se mere om fejlkoder under sektion 4.

 

Sæt dataformater

For at optimere hastigheden når der hentes større datamængder via API’et er det vigtigt at specificere hvilke data der ønskes i udtrækket. Ønskes der for eksempel data til opdatering af produkter og varianters lagerstatus kunne dette specificeres således:

$Client->Product_SetFields(array('Fields' => 'Id,Stock,Variants'));

$Client->Product_SetVariantFields(array('Fields' => 'Id,Stock'));

Dette medvirker at de returnerede data-objekter kun indeholder de specificerede felter, hvilket mindsker størrelsen af udtrækket, og derved også tiden det tager at overføre til den lokale applikation.

For større datasæt kan dét at specificere et så minimalt som muligt dataudtræk i stor grad effektivisere udtræksroutiner og deres kørselstider. Det er muligt at specificere datafelter for en række forskellige shopentiteter via:

• Product_SetFields
• Product_SetVariantFields
• Order_SetFields
• Order_SetOrderLineFields
• User_Setfields

 

Hent produkter

Denne del følger op på scenariet i 2.4 hvor der ønskes udtræk af produkter og varianters lagerstatus. Ønskes udtræk af alle produkter for en shopløsning gøres dette således:

$Client->Product_SetFields(array('Fields' => 'Id,Stock,Variants'));
$Client->Product_SetVariantFields(array('Fields' => 'Id,Stock'));
$ProductReturn = $Client->Product_GetAll();
$Products = $ProductReturn->Product_GetAllResult->item;

Bemærk at resultatet er pakket ind i variablen 'Product_getAllResult'. Dette skyldes SOAP document / literal wrapped stilen. En funktion 'x' vil altid returnere sit resultat i et objekt variabel af navnet 'xResult'.
Er resultatet yderligere et array af objekter vil dette ligge i 'item' variablen under 'xResult'.

Et eksempel på en simpel applikation til at udskrive de hentede data:

foreach ($Products as $Product) {
echo "Product: $Product->Id, stock: $Product->Stock\n";
foreach ($Product->Variants->item as $Variant) {
echo "Product: $Product->Id, variant: $Variant->Id stock: $Variant->Stock \n";
}
}

Der er en lang række muligheder for at tilpasse produkt-objektet så den passer til netop det udtræk der er brug for. En komplet beskrivelse på alle data-objekter og metoder for webservicen kan findes på https://api.hostedshop.io/doc/.

Der er ligeledes en række forskellige muligheder for at specificere hvilket produkter man ønsker i udtrækket som kan være nyttige i forskellige situationer. For eksempel  er det muligt at trække produkter ud som er blevet opdateret inden for en given periode. Ønsker man for eksempel produkter der er blevet opdateret indenfor den sidste uge:

$StartDate = date('Y-m-d', time() – 60 * 60 * 24 * 7); 
$Products = $Client->Product_GetByUpdatedDate(array('StartDate' => $StartDate));

 

Hent ordrer

Som for produkter findes der også en række forskellige funktioner til at hente ordredata. For at hente al ordedata for en shopløsning:

$Client->Order_SetFields(array('Fields' => 'Id,DateDelivered,OrderComment'));
$Client->Order_SetOrderLineFields(array('Fields' => 'Id,StockStatus'));
$Orders = $Client->Order_GetAll();

Der kan ligeledes hentes ordrer der er oprettet fra og til en specifik dato og som matcher en eller flere ordrestatus:

$Orders = $Client->Order_GetByDate(array('Start' => '2009-01-01', 'End' => '2009-02-01', 'Status' => '3,6'));

Henter således alle ordrer for perioder 1/1 2009 til 1/2 2009 med ordrestatus 3 (Ordre Sendt) eller 6 (Gennemført). For den fulde dokumentation se venligst https://api.hostedshop.io/doc/.

 

Opret nyt produkt

For at oprette et produkt skabes der først et objekt eller array med de relevante produktdata, hvorefter metoden til oprettelse af et produkt kaldes med data som argument: 

class ProductCreate {
           public $Title;
           public $LanguageIso;
           public $DescriptionLong;
...
}

$parameter                       = new ProductCreate();
$parameter->Title                = 'A title';
$parameter->DescriptionLong      = 'A long description';
$parameter->LanguageIso          = 'DK';
...

$ProductReturn = $Client->Product_Create(array('ProductData' => $parameter));
$NewProductId = $ProductReturn->ProductCreateResult;

Metoden returnerer Id’et på det oprettede produkt. Herefter kan der skabes udvidede produktdata for Produktet som eksempelvis billeder og varianter:

class ProductVariantCreate {
           public $ProductId;
           public $ItemNumber;
           public $Price;
...
}

$parameter                       = new ProductVariantCreate();
$parameter->ProductId            = $NewProductId;
$parameter->ItemNumber           = 'variant43';
$parameter->Price                = 40.2;
...

$Client->Product_CreateVariant(array('VariantData' => $parameter));

Bemærk at variantens ProductId sættes til id’et af det nyligt skabte produkt for at binde det til produktet.

 

Opdater produkt

Proceduren for at opdatere et produkt er meget lig metoden for at oprette nye produkter. Der defineres først et dataobjekt eller dataarray hvorefter en metode kaldes med objektet som argument.

class ProductUpdate {
           public $Id;
           public $Stock;
           public $CallForPrice; 
}

$parameter                       = new ProductUpdate();
$parameter->Id                   = 1337;
$parameter->Stock                = 5;
$parameter->CallForPrice         = false;

$Client->Product_Update(array ('ProductData' => $parameter));

Der er dog en række forskelle. For det første behøves man kun sætte de felter i objektet som man ønsker at opdatere. Ovenstående eksempel opdaterer således Stock og CallForPrice for produktet med id 1337, og lader de resterende felter være uændrede.

Ud over Id er det muligt at bruge varenummer til at identificere produkter man ønsker at opdatere. Der gøres opmærksom på at dette muligvis opdaterer flere end ét produkt, da varenummer ikke nødvendigvis er unikt:

class ProductUpdate {
           public $ItemNumber;
           public $Title;
           public $LanguageISO;
}

$parameter                       = new ProductUpdate();
$parameter->ItemNumber           = 'item234';
$parameter->Title                = 'En produkttitel';
$parameter->LanguageISO          = 'DK';

$Client->Product_Update(array ('ProductData' => $parameter));

opdaterer således den danske titel på alle produkter med varenummer ’item234’ . Metoden returnerer et array af id’er for de opdaterede produkter.

Angives Id under opdateringen af et produkt vil dette altid blive brugt som den identificerende del. Ønsker man således at opdatere varenummeret for et produkt er dette muligt ved at angive både Id og det nye varenummer:

class ProductUpdate {
           public $Id;
           public $ItemNumber;
}

$parameter                       = new ProductUpdate();
$parameter->Id                   = 1337;
$parameter->ItemNumber           = 'nytvarenummer';

$Client->Product_Update(array ('ProductData' => $parameter));

 

Slet produkt

For at slette et produkt angives hvilket produkt der ønskes slettet via dets unikke Id:

$Client->Product_Delete(array ('ProductId' => 1337));

 

Vælg tegnsæt

Det er muligt at sætte tegnsættet for alle tekstfelter i input og output funktioner via Solution_SetEncoding. Alle kald foretaget efter Solution_SetEncoding bruger det angivne tegnsæt.
Dette kan være nyttigt hvis man øsnker at behandle data i et givet tegnsæt. Ønskes ISO-8859-1 kaldes

$Client->Solution_SetEncoding(array ('Encoding' => 'ISO-8859-1'));

Hvis man derimod ønsker html-specialtegn i stedet for f.eks. æ, ø og å kaldes

$Client->Solution_SetEncoding(array ('Encoding' => 'HTML-ENTITIES'));

Endeligt kan der bruges UTF-8 ved at kalde

$Client->Solution_SetEncoding(array ('Encoding' => 'UTF-8'));

Det anbefales at holde sig til et tegnsæt igennem alle kald for at undgå fejl-tegnsætning.