languagesextension_dir

Chapter1:ScopeofthisDocument1HowtousePDFlibproductswithPHPLastchange:October22,2020LatestPDFlibversioncoveredinthisdocument:9.
3.
0p2Latestversionofthisdocumentavailableat:www.
pdflib.
com/documentation/howtos/Contact:PDFlibGmbHFranziska-Bilek-Weg980339München,Germanyphone+49894523384-0support@pdflib.
comwww.
pdflib.
com1ScopeofthisDocumentThisdocumentexplainsvariouspossibilitiesforsuccessfullydeployingPDFlibproductsasaPHPextension.
ThegenerictermPDFlibisusedtodesignateoneofthefollowingdistinctproducts:>ThePDFlibbaseproduct>PDFlib+PDI,asupersetofPDFlibwhichcontainsthePDFImportLibrary(PDI)>PDFlibPersonalizationServer(PPS),asupersetofPDFlib+PDIwithadvancedBlockfillingfeaturesforpersonalizingPDFdocuments.
MostofthePDFlibinformationappliestootherPDFlibGmbHproductsanalogously.
Notesforthefollowingproductsareincludedwhereapplicable:>PDFlibTET(TextandImageExtractionToolkit)>PDFlibPLOP(Linearization,Optimization,Protection)andPLOPDS(DigitalSigna-ture)ThemethodsfordeployinganyoftheseproductsasaPHPextensionarethesameinallcases.
Multipleversionsoftheseproductscannotbedeployedatthesametime.
Howev-er,multipleproductscancoexistwithinonePHPinstallation.
EvaluationversionsofPDFlibproductsarefullyfunctional,butdisplayademostampacrossallgeneratedPDFpagesunlessavalidlicensekeyisapplied.
OtherPDFlibGmbHproductshaveotherre-strictionsinevaluationmode(seedocumentation).
ThisdocumentappliestothefollowingversionsofPDFlibGmbHproducts:>PDFlib9.
3.
0p2>TET5.
3>PLOPandPLOPDS5.
5Whereapplicable,version-specificinformationisprovidedseparately.
2ThePDFlib-in-PHPHowTo2Platforms,PHPVersionsandThreadSafetySupportedplatforms.
PDFlibGmbHproductsforusewithPHPareasloadableexten-sionmoduleswhichareimplementedasDSOs(dynamicsharedobjects,alsocalleddy-namiclinklibraryDLL).
Theyareavailableonthefollowingplatforms:>WindowsServerx86/x64andWindows7/8/10x86/x64>macOS>Linuxonx86andIntel64>AlpineLinuxonIntel64>LinuxonzSeries>FreeBSDIntel64SupportedPHPversions.
ThedistributionpackagesshippedbyPDFlibGmbHcontainDSOsforseveralPHPversions.
Thesearegroupedintodirectoriesasfollows(notallPHPversionsaresupportedonallplatforms,though):>bind/php/php-730forPHP7.
3.
x>bind/php/php-740forPHP7.
4.
x>bind/php/php-800forPHP8.
0.
xThreadsafety.
OnmostplatformstwovariantsofthePHPbinaryareavailable,andthePDFlibDSOmustmatchtheselectedPHPversion:>Thread-safe(TS):thisversionshouldgenerallybeusedwhenloadingPHPasamod-uleintoaWebserver.
Thethread-safeversionshouldbeusedwhenloadingPHPasanApachemodule.
>Non-thread-safe(NTS):thisversionincludesntsinthedirectorynameandshouldgenerallybeusedwhenusingPHPinaWebserverthroughFastCGIprotocol,work-ingwiththecommand-lineinterface(CLI),orintegratingPHPwithIISviaFastCGI.
RefertothePHPWebsiteformoreinformationregardingTSandNTSversionsofPHP.
Chapter3:RequiredSkillLevels33RequiredSkillLevelsMakingPDFlibworkwithPHPrequiresvariousskilllevelsdependingonyouroperatingsystemplatform.
Wewillclassifytasksaccordingtothefollowingskillsets:>APHPWebprogrammerknowshowtowritecodeforPHP,butdoesn'thaveexperi-encewithotherlanguagesorgeneralsystemadministrationtasks.
ThePHPpro-grammerusuallyhasaccesstootherpeoplewhoareresponsibleforperformingcon-figurationtasks.
>AsysadminfeelscomfortableworkingwithPEARandothercommand-linetools,hap-pilyeditsphp.
inianddoesnothesitatetorestarttheWebserver(i.
e.
ApacheorIIS)ifrequiredforinstallationorconfigurationpurposes.
Appropriatepermissions(accessrights)todoallthisarealsopartofthesysadminprofile.
>ACdeveloperhasaccesstoaCdevelopmentenvironment(headerfiles,compiler,linker,associatedsystemlibraries)andcanworkwithconfigurescriptsandMake-filesorcorrespondingIDEfeatures.
Itmayhelptoclassifyyourselfaccordingtothesetypesofdevelopers.
TheremainderofthisdocumentdescribestaskswhichrequireatleastsysadminorCdeveloperskills.
PHPdeveloperswithoutadditionalknowledgeorassistancewillnotbeabletoperformtherequiredstepswithoutassistance.
4ThePDFlib-in-PHPHowTo4TestingyourInstallationAfteryouinstalledyourPDFlibproductextensionforPHPusinganyofthemethodsdiscussedinthisdocumentyoumaywanttotestyourinstallationinordertoseewhethereverythingworksasexpected.
ThePHPinfopage.
YoucantestthesuccessofyourPDFlibproductinstallationandconfigurationwiththefollowingsmallPHPscript:Checktheoutputcreatedbyphpinfo().
IfitcontainsthelinePDFlibGmbHBinaryVersionyouareusingaprecompiledPDFlibDSOprovidedbyPDFlibGmbH.
Ifyoudon'tfindanyPDFlibsectioncheckyourlogfilestodeterminethereason.
ThePDFlibproductexamples.
ThedistributionpackageofyourPDFlibproductcon-tainsexamplesinthebind/phpdirectory.
Youcanusethemtotestyourinstallationasfollows:>CopythePHPsamplesanddatafilestoyourhtdocsdirectoryoranotherdirectorywhichhasbeenconfiguredappropriatelyintheWebserver:cp-rbind/php/path/to/htdocscp-rbind/data/path/to/htdocs>pointyourbrowsertotheURLsoftheexamples>enjoythegeneratedPDFsChapter5:PDFlibinHostingEnvironments55PDFlibinHostingEnvironmentsYouarerunningasiteataWebhostingprovider.
Inthiscasetherearevariousconsid-erations(wecanignorethecasewhereaPDFlibextensionforPHPisalreadyinstalledsincethere'snothingmoretodo):>SomeprovidersdonotallowcustomPHPextensions;inthiscaseyouareoutofluck.
>Withsomeprovidersyoucanmaintainyourowncopyofphp.
ini,whileothersdon'tallowthis.
Ifyoucan'teditphp.
iniandthisfilecontainsenable_dl=Offyouareoutofluck.
YouareaWebhostingprovider.
Asaprovideryoushouldbeawareofthefollowing:>AlthoughPDFlibLitesourcecodeisfreelyavailable,andmanyLinuxandPHPdistri-butionscontainPDFlibLite,thePDFlibLitelicensedoesnotcoverfreeuseofPDFlibLiteonaWebhoster'ssystems.
>YoucaninstallcommercialPDFlibDSOsevenwithoutobtainingalicense.
Inthissit-uationyoucaninstalloneoftheprecompiledPDFlibDSOssuppliedbyPDFlibGmbHwithoutalicensekey(i.
e.
ademostampwillbecreated).
Thoseamongyourcustom-erswhowishtocommerciallyuseitcanobtainacommerciallicensetodisablethedemostamp.
Inotherwords,youcanofferPDFlibwithouttheneedforobtainingali-censeforallofyourservers.
TherecommendedmethodistoinstallthePDFlibDSOinsomegloballyaccessibledirectory,andsettheextension=lineinphp.
iniappropri-ately.
>Alternatively,if(likeanincreasingnumberofproviders)youbelieveinPDFlibavail-abilityasacompetitiveadvantage,youcanobtainasitelicensewhichcoversallyourserversandcustomers.
Individualuserswillnolongerberequiredtoobtainalicenseontheirowninthiscase.
PleasecontactPDFlibGmbHifyouareinterestedinmoredetails.
6ThePDFlib-in-PHPHowTo6DeployingthePDFlibDSONoteInadditiontothePDFlibproductfamily,thissectionalsoappliestoPDFlibTETandPDFlibPLOPifyoureplacethestringphp_pdflibwithphp_tetorphp_plop.
Requirements:>Skilllevel:sysadmin>ThePDFlibDSO,eitherbuiltonyourownor(preferably)fromabinarypackagepro-videdbyPDFlibGmbHatwww.
pdflib.
com/download/pdflib-product-family/>WorkingPHPbinaryThissectionappliestotheprecompiledDSOsdistributedbyPDFlibGmbH,aswellastoDSOswhichyouhavebuiltyourself.
6.
1InstallingthePDFlibDSOonWindowsThePDFlibDSOsforWindows(actuallyDLLs)havebeentestedwiththebinaryPHPdis-tributionwhichisavailablefromwindows.
php.
net.
YouwillfindPDFlibDSOsforvariousversionsofPHPonWindowswithandwithoutmulti-threadingsupportinthedistribu-tionpackage.
DependingonthetargetPHPversionthePDFlibDSOshavebeenbuiltwithdifferentversionsofVisualStudio,whichmeansthatthecorrespondingredistributableruntimeDLLsmustbeavailableonthesystem:>ThePDFlibDSOsforPHP7.
0and7.
1havebeenbuiltwithVisualStudio2015(VC14).
>ThePDFlibDSOsforPHP7.
2havebeenbuiltwithVisualStudio2017(VC15).
ForthePHPinstallationprocesspleasefollowthedocumentationofyourPHPdistribu-tionandcopythePDFlibDSOtothedirectorywhichisspecifiedintheextension_dirlineinphp.
ini.
6.
2InstallingthePDFlibDSOonUnixThePDFlibDSOsforvariousUnixplatformswithandwithoutmulti-threadingsupportareavailablefordifferentversionsofPHP.
YouwillfindPDFlibDSOsinthefollowinglo-cationofthedistributionpackage(adjustthesharedlibrarysuffixasnecessaryforyourplatform):bind/php/php-/php_pdflib.
soCopythePDFlibDSOtothedirectorywhichisspecifiedintheextension_dirlineinphp.
ini.
UsingPDFlibwithZendServer.
InordertousePDFlibwithZendServeryoumustin-stalltheDSOphp_pdflib.
sofromthephp-directory.
CopythisDSOtotheexten-siondirectoryandrestartPHP.
6.
3InstallingthePDFlibDSOonmacOSwithSIPThegeneralinstallationprocedureformacOSisthesameasonUnixsystems(seeabove).
However,therearesomeadditionalaspectswhenApple'sSystemIntegrityPro-tection(SIP)isinvolved.
WhenSIPisenabledthePHPbinarywhichcomespreinstalledChapter6:DeployingthePDFlibDSO7withmacOS10.
14Mojaveacceptsonlysignedextensions,andextensionsmustbeload-edfromoneoftheprotectedsystemdirectoriesforlibraries.
Otherextensiondirecto-riesarenotaccepted.
ThePDFlibDSOissignedbyPDFlibGmbH,butinstallationre-quiressomeextrastepsonsystemswithactiveSIP.
ThesestepsarenotrequiredforotherbuildsofthePHPbinary,e.
g.
thosefromHomebrew.
Step1:TemporarilydisableSystemIntegrityProtection(SIP).
Thisrequiresrebootingintorecoverymode:>Restartthesystemandpresscmd-RuntiltheApplelogoappears.
>SelectTerminalfromtheUtilitiesmenu.
>InthewindowthatopenstypecsrutildisableandpressreturntodisableSystemIn-tegrityProtection.
>ChooseRestartfromtheApplemenu.
Step2:InstallthePDFlibDSOinthePHPextensiondirectory.
CopytheappropriateversionofthePDFlibDSOtotheextensiondirectoryofthepreinstalledPHPbinary,e.
g.
cpbind/php/php-710-nts/php_pdflib.
so/usr/lib/php/extensions/no-debug-non-zts-20160303/Step3:EnableSystemIntegrityProtectionagain.
Thisrequiresrebootingagain:>Restartthesystemandpresscmd-RuntiltheApplelogoappears.
>SelectTerminalfromtheUtilitiesmenu.
>InthewindowthatopenstypecsrutilenableandpressreturntoenableSystemInteg-rityProtection.
ThisensuresthatyourmachineisfullyprotectedbySIP.
>ChooseRestartfromtheApplemenu.
NowconfigurethePDFlibextensionforPHPwithoneofthemethodsdescribedinthenextsection.
6.
4UsingthePDFlibDSOLoadingthePDFlibDSOinphp.
ini.
IfyoudecidetoloadthePDFlibDSOeverytimePHPstarts,insertthefollowinglineinphp.
ini(adjustthesharedlibrarysuffix.
dllasnec-essaryforyourplatform,e.
g.
.
so):extension=php_pdflib.
dllandrestartyourWebserversothatthechangesarerecognized.
Custompdflib.
inifile.
IfyourPHPversionsupportsadditional.
inifilesparsingyoucancreateapdflib.
iniconfigurationfilewithasinglelineasfollows(adjustthesharedli-brarysuffix.
dllasnecessaryforyourplatform,e.
g.
.
so):extension=php_pdflib.
dllinthePHP_INI_SCAN_DIRdirectory.
8ThePDFlib-in-PHPHowTo6.
5CommonProblemswithPDFlibDSOs6.
5.
1AllPlatformsBinarycharacteristicsofPHPandPDFlibDSOmustmatch.
SeveralpropertiesofyourPHPbinarymustmatchthecorrespondingpropertiesofthePDFlibDSO.
Theseproper-tiesaredeterminedwhenbuildingPHPandcannotbechangedafterwards.
Theprecom-piledDSOsforPDFlibhavebeenbuiltasfollows:>non-debugversion>withorwithoutmulti-threadingsupport(seeThreadsafety,page2)>theAPIversion:choosethematchingversionfrombind/php/php-IfyouseeanerrormessagesimilartothefollowingwhentryingtoloadthePDFlibDSO,yourPHPbuildnumberdoesnotmatchthatofthePDFlibmodule:Warning:PHPStartup:PDFlib:UnabletoinitializemoduleModulecompiledwithbuildID=API20190902,TSPHPcompiledwithbuildID=API20190902,NTSTheseoptionsneedtomatchinUnknownonline0Alloftheseoptionsmustmatch.
Intheexampleaboveitwasattemptedtoloadthenon-thread-safeDSOintoathread-safePHPbinary.
6.
5.
2Linuxx86andIntel64PDFlibwithXAMPPonLinuxx86.
SomeversionsofsystemlibrariesbundledwiththeXAMPPpackagemaytriggerthefollowingerrormessage:Warning:PHPStartup:Unabletoloaddynamiclibrary'/opt/lampp/htdocs/test/pdf/pdflib/bind/php/php-720/php_pdflib.
so'-/opt/lampp/lib/libgcc_s.
so.
1:version`GCC_4.
2.
0'notfound(requiredby/usr/lib/libstdc++.
so.
6)inUnknownonline0Inthiscaseyoumustdisablethefollowingtwolinesinthefilebin/envvars,e.
g.
byadd-ingacommentcharacteratthestartoftheline:#binbuildLD_LIBRARY_PATH="/opt/lampp/lib/:$LD_LIBRARY_PATH"#binbuildexportLD_LIBRARY_PATHPDFlibwithXAMPPonLinuxIntel64.
Ifyouareusingthe32-biteditionofXAMPPyoumustusethe32-biteditionofPDFlibforthiscombination.
However,youmayseethefollowingerrormessage:Warning:PHPStartup:Unabletoloaddynamiclibrary'/opt/lampp/htdocs/test/pdf/PDFlib-x.
y.
z-Linux-php/bind/php/php-720/php_pdflib.
so'-libstdc++.
so.
6:wrongELFclass:ELFCLASS64inUnknownonline0ThereasonforthiserroristhatwhileXAMPPincludessomeofthe32-bitruntimelibrar-iesrequiredforPDFlib,oneimportantruntimelibraryisstillmissing.
Youmustinstallthe32-bitversionoflibstdc++.
so.
6onthesystem.
Forexample,onDebiansystemsthiscanbeachievedwiththefollowingcommand:apt-getinstallia32-libsChapter6:DeployingthePDFlibDSO96.
5.
3macOSPDFlibwithXAMPPonmacOS.
IfyouaddthePDFlibPHPextensiontoyourphp.
inionanmacOSIntelmachinewhichhasXAMPPinstalled,thefollowingerrormessageap-pears:dyld:NSLinkModule()errordyld:Symbolnotfound:__cg_jpeg_resync_to_restartReferencedfrom:/System/Library/Frameworks/ApplicationServices.
framework/Versions/A/Frameworks/ImageIO.
framework/Versions/A/ImageIOExpectedin:/Applications/xampp/xamppfiles/lib/libjpeg.
62.
dylibThePDFlibextensionislinkedagainsttheApplicationServicesFramework,andXAMPPchangestheDYLD_LIBRARY_PATH.
Thiscombinationconfusesthedynamiclinkeditor.
WefoundthatunsettingDYLD_LIBRARY_PATHcuresthisproblem.
Usethefollowinglineaslastcommandinxamppfiles/bin/envvars:unsetDYLD_LIBRARY_PATH10ThePDFlib-in-PHPHowTo7AdditionalResources>ThepublicPDFlibmailinglistforgeneraldiscussion:groups.
yahoo.
com/neo/groups/pdflib/conversations/topics>PDFlibsupportforcommerciallicensees:support@pdflib.
com>GeneralinformationoninstallingPHP:www.
php.
net/install