README

此包可以将包含LaTeX源代码的Blade视图编译成PDF文件

需求

您需要在服务器上安装LaTeX编译器（例如texlive）。此包是为与Laravel 10或更高版本一起使用而设计的。从2.0.0版本开始，需要PHP 8.1。

较旧的Laravel版本

对于laravel 8和9，使用此包的^1.3版本。

安装和设置

使用composer安装

composer require abiturma/laravel-latex

服务提供者和外观将通过laravel包自动发现自动安装。

要发布配置文件到config/latex.php，请运行

php artisan vendor:publish --provider="Abiturma\LaravelLatex\LatexServiceProvider

默认配置如下所示

return [
    'temp_directory' => storage_path().'/latex/temp',
    'output' => [
        'disk' => 'local',
        'path' => 'latex/output' 
    ],
    'debug' => false, 
    'pdflatex' => env('PATH_TO_PDFLATEX','pdflatex')
];

使用键pdflatex，您必须设置服务器上pdflatex二进制的绝对路径。

用法

您可以通过调用外观Latex或注入类Abiturma\LaravelLatex\LatexToPdf来编译blade视图。在文档中，我们将

基本用法

该类有一个流畅的接口，通过调用->get()来终止调用以开始编译。

您必须传递一个blade视图以及视图的数据。一个标准用例如下所示

use Latex

...

$pdf = Latex::view('your.favourite.latex.view')
    ->with(['key' => 'value'])
    ->get()

返回值将是编译后的pdf的路径。该路径相对于您在配置文件中指定的存储磁盘的根目录。

...

Storage::disk(config('latex.output.disk'))
->exists($pdf) //true 

转义输入

由于LaTeX有自己的语法，因此不建议使用标准的blade语法{{ $variable }}或{{!! $variable !!}}。相反，您可以在blade模板中使用@latex($variable)，它会处理保留的LaTeX字符的适当转义。

多次运行

为了使LaTeX能够处理交叉引用，有时需要多次编译文档。您可以通过以下方式指定运行次数

    Latex::view('myView')->runs($numberOfRuns)->get()

运行的次数将自动截断为介于1和10之间的整数。

资产文件

一旦您在模板中使用图形或自定义sty文件，您的编译器就需要多个文件。为了处理这种情况，您可以在编译器上调用

->assets([
    './relative/path/to/one/asset',
    './relative/path/to/another/asset
])

这将把所有指定的文件复制到编译目录。路径相对于视图的目录。如果需要绝对路径，将absolutePath标志设置为true

->assets([
    '/absolute/path/to/asset',
    '/absolute/path/to/another/asset
],
true)

通常，您可能希望将视图目录中的所有文件作为资产包含。在这种情况下，您可以在编译器上简单地调用->includeViewFolder()。这将复制视图的环境目录中的所有文件到编译目录。

在将资产文件复制到编译目录后，所有blade视图都使用通过->with($data)传递的变量编译成相应的tex文件。

示例

给定以下树结构

views
│
└── myDocument
     │   main.blade.php
     │   package.sty.blade.php 
     │   picture.jpg
    ...

命令

Latex::view('myDocument.main)
    ->with($data)
    ->includeViewFolder()
    ->get()

将产生一个（临时的）编译目录，形式如下

temp
│
└── #someHash
     │   main.tex
     │   package.sty 
     │   picture.jpg
    ...

其中package.sty是使用$data编译的package.sty.blade.php的版本。

使用Texables

您也可以传递一个Texable类来代替调用带有所有必要参数的编译器，该类类似于Laravel Mailables。

要创建一个可邮寄的运行，请在视图目录中运行命令 latex:make MyTexable 以创建一个占位符。

要编译一个可编译的文件，运行 make::latex(new MyTexable())。可编译文件基本上具有与编译器类相同的方法。在 LaTeX 编译器运行之前，会对可编译文件的 ->build() 方法进行调用。此外，可编译文件上的所有公共变量都作为给定视图的数据可用。

示例

假设类 MyTexable 定义如下

use Abiturma\LaravelLatex\Texable

class MyTexable extends Texable
{
    public $message;     

    __construct($message) {
        $this->message = $message;        
    }

    public function build() {
        return $this->view('someview')
    }
    
}

然后运行 Latex::make(MyTexable("someString") 等价于

Latex::view('someview')->with(["message" => "someString"])->get()

资产

除了 ->asset() 方法外，可编译文件还有更多处理资产的选择。可以使用 ->addAsset() 添加资产。这些方法不仅通过 absolutePath 标志（作为第二个参数）理解绝对和相对路径，还可以解析文件模式作为 glob。因此，也可以这样添加资产：->addAsset('*.jpg')。要排除文件模式，请使用方法 ->excludeAssets($assets)

调试

如果编译失败，则会抛出 CompilationFailedException。默认情况下，异常消息包含截断的编译日志。如果将 debug 设置为 true，则异常消息包含完整的编译日志。

命令

测试

命令 latex:test 在两个测试文件上运行编译器。如果编译成功，则打印文件的输出路径。

垃圾回收

命令 latex:gc 删除在编译过程中未进行垃圾回收的所有临时目录和文件。这可能发生在编译过程在编译器的自动清理过程之前失败的情况下。

如果添加 --output 标志，则还会清理指定的输出目录。如果您习惯于将生成的输出文件移动到其他位置，这很有意义。

升级/破坏性更改

从版本 1.2.0 开始，LatexToPdf 和可编译类上的 ->assets() 方法现在期望路径相对于视图文件夹，而不是绝对路径。为了向下兼容，请使用 absolutePath 标志作为第二个参数，例如 ->assets($someLegacyPath, true)。

致谢

本项目灵感来源于 latexcompiler，作者为 Vernon Hockney。