Qual: Improve write_file typing (part 2) (#30527)

* Qual: Add abstract write_file to ModeleDon And update phpdoc for derived classes * Qual: Add abstract write_file to ModeleChequeReceipts And update phpdoc for derived classes * Qual: Add abstract write_file to ModelePDFRecruitmentCandidature And update phpdoc for derived classes * Qual: Add abstract write_file to ModelePDFStock & ModelePDFStockTransfer And update phpdoc for derived classes * Qual: Update phpdoc write_file for CommonStickerGenerator classes --------- Co-authored-by: Laurent Destailleur <eldy@destailleur.fr>
Dolibarr · Nov 13, 2024 · a0f515e · a0f515e
1 parent ba46e7d
commit a0f515e
Show file tree

Hide file tree

Showing 13 changed files with 68 additions and 32 deletions.
diff --git a/htdocs/core/class/commonstickergenerator.class.php b/htdocs/core/class/commonstickergenerator.class.php
@@ -131,13 +131,14 @@ public function __construct($db)
 	/**
 	 *  Function to build PDF on disk, then output on HTTP stream.
 	 *
-	 *  @param	array<string,mixed>		$arrayofrecords  	Array of record information (array('textleft'=>,'textheader'=>, ..., 'id'=>,'photo'=>)
+	 *  @param  Adherent|array<array{textleft:string,textheader:string,textfooter:string,textright:string,id:string,photo:string}>   $arrayofrecords     Array of record information (array('textleft'=>,'textheader'=>, ..., 'id'=>,'photo'=>)
 	 *  @param  Translate	$outputlangs     	Lang object for output language
 	 *  @param	string		$srctemplatepath	Full path of source filename for generator using a template file
-	 *	@param	string		$outputdir			Output directory for pdf file
-	 *  @return int             				1=OK, 0=KO
+	 *  @param  string		$outputdir			Output directory for pdf file
+	 *  @param  string		$filename           Short file name of output file
+	 *  @return int<-1,1>                       1=OK, <=0=KO
 	 */
-	abstract public function write_file($arrayofrecords, $outputlangs, $srctemplatepath, $outputdir = '');
+	abstract public function write_file($arrayofrecords, $outputlangs, $srctemplatepath, $outputdir = '', $filename = '');
 	// phpcs:enable
 
 	/**

diff --git a/htdocs/core/modules/cheque/doc/pdf_blochet.class.php b/htdocs/core/modules/cheque/doc/pdf_blochet.class.php
@@ -116,7 +116,7 @@ public function __construct($db)
 	 *	@param	string			$_dir			Directory
 	 *	@param	string			$number			Number
 	 *	@param	Translate		$outputlangs	Lang output object
-	 *	@return	int     						1=ok, 0=ko
+	 *	@return	int<-1,1>							1 if OK, <=0 if KO
 	 */
 	public function write_file($object, $_dir, $number, $outputlangs)
 	{

diff --git a/htdocs/core/modules/cheque/modules_chequereceipts.php b/htdocs/core/modules/cheque/modules_chequereceipts.php
@@ -111,6 +111,8 @@ public static function liste_modeles($db, $maxfilenamelength = 0)
 
 		return $list;
 	}
+
+
 	// phpcs:disable PEAR.NamingConventions.ValidFunctionName.ScopeNotCamelCaps
 	/**
 	 *	Fonction to generate document on disk
@@ -167,7 +169,8 @@ function chequereceipt_pdf_create($db, $id, $message, $modele, $outputlangs)
 		// We save charset_output to restore it because write_file can change it if needed for
 		// output format that does not support UTF8.
 		$sav_charset_output = $outputlangs->charset_output;
-		if ($obj->write_file($id, $outputlangs) > 0) {
+		// TODO: write_file seems invalid, function is likely no longer used - delete ?
+		if ($obj->write_file($id, $outputlangs) > 0) { // @phan-suppress-current-line PhanParamTooFew,PhanPluginSuspiciousParamPosition
 			$outputlangs->charset_output = $sav_charset_output;
 			return 1;
 		} else {

diff --git a/htdocs/core/modules/dons/html_cerfafr.modules.php b/htdocs/core/modules/dons/html_cerfafr.modules.php
@@ -69,10 +69,10 @@ public function isEnabled()
 	/**
 	 *  Write the object to document file to disk
 	 *
-	 *	@param	Don			$don	        Donation object
-	 *  @param  Translate	$outputlangs    Lang object for output language
+	 *	@param	Don			$don			Donation object
+	 *  @param  Translate	$outputlangs	Lang object for output language
 	 *  @param	string		$currency		Currency code
-	 *	@return	int             			>0 if OK, <0 if KO
+	 *	@return	int<-1,1>					>0 if OK, <0 if KO
 	 */
 	public function write_file($don, $outputlangs, $currency = '')
 	{

diff --git a/htdocs/core/modules/dons/html_generic.modules.php b/htdocs/core/modules/dons/html_generic.modules.php
@@ -186,10 +186,10 @@ private function saveFile($path, $contents)
 	/**
 	 *  Write the object to document file to disk
 	 *
-	 *  @param	Don			$don	        Donation object
-	 *  @param	Translate	$outputlangs    Lang object for output language
+	 *  @param	Don			$don			Donation object
+	 *  @param	Translate	$outputlangs	Lang object for output language
 	 *  @param	string		$currency		Currency code
-	 *  @return	int             			>0 if OK, <0 if KO
+	 *  @return	int<-1,1>					>0 if OK, <0 if KO
 	 */
 	public function write_file($don, $outputlangs, $currency = '')
 	{

diff --git a/htdocs/core/modules/dons/modules_don.php b/htdocs/core/modules/dons/modules_don.php
@@ -55,6 +55,17 @@ public static function liste_modeles($db, $maxfilenamelength = 0)
 
 		return $list;
 	}
+
+	// phpcs:disable PEAR.NamingConventions.ValidFunctionName.ScopeNotCamelCaps
+	/**
+	 *  Write the object to document file to disk
+	 *
+	 *  @param	Don			$don			Donation object
+	 *  @param	Translate	$outputlangs	Lang object for output language
+	 *  @param	string		$currency		Currency code
+	 *  @return	int<-1,1>					>0 if OK, <0 if KO
+	 */
+	abstract public function write_file($don, $outputlangs, $currency = '');
 }
 
 

diff --git a/htdocs/core/modules/member/doc/pdf_standard_member.class.php b/htdocs/core/modules/member/doc/pdf_standard_member.class.php
@@ -262,17 +262,17 @@ public function Add_PDF_card(&$pdf, $textleft, $header, $footer, $outputlangs, $
 
 	// phpcs:disable PEAR.NamingConventions.ValidFunctionName.ScopeNotCamelCaps
 	/**
-	 *	Function to build PDF on disk, then output on HTTP stream.
+	 *  Function to build PDF on disk, then output on HTTP stream.
 	 *
-	 *	@param	Adherent|array	    $object		        Member object. Old usage: Array of record information (array('textleft'=>,'textheader'=>, ...'id'=>,'photo'=>)
-	 *	@param	Translate			$outputlangs		Lang object for output language
-	 *	@param	string				$srctemplatepath	Full path of source filename for generator using a template file. Example: '5161', 'AVERYC32010', 'CARD', ...
-	 *	@param	string				$mode				Tell if doc module is called for 'member', ...
-	 *  @param  int         		$nooutput           1=Generate only file on disk and do not return it on response
-	 *  @param	string				$filename			Name of output file (without extension)
-	 *	@return	int								1=OK, 0=KO
+	 *  @param  Adherent|array<array{textleft:string,textheader:string,textfooter:string,textright:string,id:string,photo:string}>   $object     Array of record information (array('textleft'=>,'textheader'=>, ..., 'id'=>,'photo'=>)
+	 *  @param  Translate	$outputlangs		Lang object for output language
+	 *  @param  string		$srctemplatepath	file. Example: '5161', 'AVERYC32010', 'CARD', ...
+	 *  @param  string		$mode				Tell if doc module is called
+	 *  @param  string		$nooutput			1=Generate only file on disk and do not return it on response // TODO: Fix not compatible parameter signature.
+	 *  @param  string		$filename			Name of output file (without extension)
+	 *  @return int<-1,1>                       1=OK, <=0=KO
 	 */
-	public function write_file($object, $outputlangs, $srctemplatepath, $mode = 'member', $nooutput = 0, $filename = 'tmp_cards')
+	public function write_file($object, $outputlangs, $srctemplatepath, $mode = 'member', $nooutput = '', $filename = 'tmp_cards')
 	{
 		// phpcs:enable
 		global $user, $conf, $langs, $mysoc, $_Avery_Labels;

diff --git a/htdocs/core/modules/printsheet/doc/pdf_standardlabel.class.php b/htdocs/core/modules/printsheet/doc/pdf_standardlabel.class.php
@@ -228,12 +228,12 @@ public function Add_PDF_label(&$pdf, $textleft, $header, $footer, $outputlangs,
 	/**
 	 *	Function to build PDF on disk, then output on HTTP stream.
 	 *
-	 *	@param	array<array{textleft:string,textheader:string,textfooter:string,textright:string,photo:string}>		$arrayofrecords		Array of record information (array('textleft'=>,'textheader'=>, ..., 'id'=>,'photo'=>)
+	 *	@param	array<array{textleft:string,textheader:string,textfooter:string,textright:string,id:string,photo:string}>	$arrayofrecords		Array of record information (array('textleft'=>,'textheader'=>, ..., 'id'=>,'photo'=>)
 	 *	@param	Translate	$outputlangs		Lang object for output language
 	 *	@param	string		$srctemplatepath	Full path of source filename for generator using a template file
 	 *	@param	string		$outputdir			Output directory for pdf file
 	 *  @param  string      $filename           Short file name of PDF output file
-	 *	@return int								1=OK, 0=KO
+	 *  @return int<-1,1>                       1=OK, <=0=KO
 	 */
 	public function write_file($arrayofrecords, $outputlangs, $srctemplatepath, $outputdir = '', $filename = 'tmp_address_sheet.pdf')
 	{

diff --git a/htdocs/core/modules/printsheet/doc/pdf_tcpdflabel.class.php b/htdocs/core/modules/printsheet/doc/pdf_tcpdflabel.class.php
@@ -250,14 +250,14 @@ public function addSticker(&$pdf, $outputlangs, $param)
 
 	// phpcs:disable PEAR.NamingConventions.ValidFunctionName.ScopeNotCamelCaps
 	/**
-	 *	Function to build PDF on disk, then output on HTTP stream.
+	 *  Function to build PDF on disk, then output on HTTP stream.
 	 *
 	 *	@param	Adherent|array<array{textleft:string,textheader:string,textfooter:string,textright:string,code:string,encoding:string,is2d:int<0,1>|bool}>	$arrayofrecords		Array of record information (array('textleft'=>,'textheader'=>, ..., 'id'=>,'photo'=>)
 	 *	@param	Translate	$outputlangs		Lang object for output language
 	 *	@param	string		$srctemplatepath	Full path of source filename for generator using a template file
 	 *	@param	string		$outputdir			Output directory for pdf file
 	 *  @param  string      $filename           Short file name of PDF output file
-	 *	@return int								1=OK, 0=KO
+	 *  @return int<-1,1>                       1=OK, <=0=KO
 	 */
 	public function write_file($arrayofrecords, $outputlangs, $srctemplatepath, $outputdir = '', $filename = 'tmp_address_sheet.pdf')
 	{

diff --git a/htdocs/core/modules/stocktransfer/doc/pdf_eagle.modules.php b/htdocs/core/modules/stocktransfer/doc/pdf_eagle.modules.php
@@ -169,17 +169,18 @@ public function __construct(DoliDB $db)
 		}
 	}
 
+
 	// phpcs:disable PEAR.NamingConventions.ValidFunctionName.ScopeNotCamelCaps
 	/**
 	 *	Function to build pdf onto disk
 	 *
 	 *	@param		StockTransfer	$object				Object StockTransfer to generate (or id if old method)
-	 *	@param		Translate		$outputlangs		Lang output object
+	 *  @param		Translate		$outputlangs		Lang output object
 	 *  @param		string			$srctemplatepath	Full path of source filename for generator using a template file
 	 *  @param		int<0,1>		$hidedetails		Do not show line details
 	 *  @param		int<0,1>		$hidedesc			Do not show desc
 	 *  @param		int<0,1>		$hideref			Do not show ref
-	 *  @return     int<-1,1>      	    				1=OK, 0=KO
+	 *  @return		int<-1,1>							1 if OK, <=0 if KO
 	 */
 	public function write_file($object, $outputlangs, $srctemplatepath = '', $hidedetails = 0, $hidedesc = 0, $hideref = 0)
 	{

diff --git a/htdocs/don/class/don.class.php b/htdocs/don/class/don.class.php
@@ -1019,14 +1019,14 @@ public function info($id)
 
 
 	/**
-	 *  Create a document onto disk according to template module.
+	 *  Create a document on disk according to template module.
 	 *
 	 *  @param	    string		$modele			Force template to use ('' to not force)
 	 *  @param		Translate	$outputlangs	object lang a utiliser pour traduction
-	 *  @param      int			$hidedetails    Hide details of lines
-	 *  @param      int			$hidedesc       Hide description
-	 *  @param      int			$hideref        Hide ref
-	 *  @return     int         				0 if KO, 1 if OK
+	 *  @param      int<0,1>	$hidedetails    Hide details of lines
+	 *  @param      int<0,1>	$hidedesc       Hide description
+	 *  @param      int<0,1>	$hideref        Hide ref
+	 *  @return     int<-1,1>      				0 if KO, 1 if OK
 	 */
 	public function generateDocument($modele, $outputlangs, $hidedetails = 0, $hidedesc = 0, $hideref = 0)
 	{
@@ -1098,6 +1098,8 @@ public function generateDocument($modele, $outputlangs, $hidedetails = 0, $hided
 			$classname = $modele;
 			$obj = new $classname($this->db);
 
+			'@phan-var-force ModeleDon $obj';
+
 			// We save charset_output to restore it because write_file can change it if needed for
 			// output format that does not support UTF8.
 			$sav_charset_output = $outputlangs->charset_output;

diff --git a/htdocs/recruitment/admin/setup_candidatures.php b/htdocs/recruitment/admin/setup_candidatures.php
@@ -118,6 +118,8 @@
 
 		$module = new $classname($db);
 
+		'@phan-var-force ModelePDFRecruitmentCandidature $module';
+
 		if ($module->write_file($tmpobject, $langs) > 0) {
 			header("Location: ".DOL_URL_ROOT."/document.php?modulepart=".strtolower($tmpobjectkey)."&file=SPECIMEN.pdf");
 			return;

diff --git a/htdocs/recruitment/core/modules/recruitment/modules_recruitmentcandidature.php b/htdocs/recruitment/core/modules/recruitment/modules_recruitmentcandidature.php
@@ -58,6 +58,22 @@ public static function liste_modeles($db, $maxfilenamelength = 0)
 
 		return $list;
 	}
+
+
+	// phpcs:disable PEAR.NamingConventions.ValidFunctionName.ScopeNotCamelCaps
+	/**
+	 *  Function to build a document on disk using the generic odt module.
+	 *
+	 *	@param	RecruitmentCandidature	$object				Object source to build document
+	 *	@param	Translate				$outputlangs		Lang output object
+	 *	@param	string					$srctemplatepath	Full path of source filename for generator using a template file
+	 *	@param	int<0,1>				$hidedetails		Do not show line details
+	 *	@param	int<0,1>				$hidedesc			Do not show desc
+	 *	@param	int<0,1>				$hideref			Do not show ref
+	 *	@return	int<-1,1>									1 if OK, <=0 if KO
+	 */
+	abstract public function write_file($object, $outputlangs, $srctemplatepath = '', $hidedetails = 0, $hidedesc = 0, $hideref = 0);
+	// phpcs:enable
 }